From 68ec0789e9c1d7571f20c924f1ab31468cda4aa6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Wed, 3 Jun 2026 15:34:37 -0300
Subject: [PATCH 1/4] feat: add Copy Button and Tooltip components

Introduce copy-button and tooltip with Storybook coverage, icon swap
transitions on IconButton, and package exports for consumers.
---
 .specs/copy-button.md                         | 114 +++++++
 .specs/tooltip.md                             | 131 ++++++++
 .../actions/copy-button/CopyButton.stories.js | 108 +++++++
 .../stories/webkit/overlay/Tooltip.stories.js | 190 ++++++++++++
 packages/webkit/package.json                  |   2 +
 .../actions/copy-button/copy-button.vue       |  96 ++++++
 .../actions/icon-button/icon-button.vue       |  67 +++-
 .../icon-button/presets/icon-transition.js    |  24 ++
 .../components/overlay/tooltip/package.json   |  11 +
 .../tooltip/presets/popup-scale-transition.js |  31 ++
 .../overlay/tooltip/tooltip.figma.ts          |  18 ++
 .../components/overlay/tooltip/tooltip.vue    | 291 ++++++++++++++++++
 12 files changed, 1074 insertions(+), 9 deletions(-)
 create mode 100644 .specs/copy-button.md
 create mode 100644 .specs/tooltip.md
 create mode 100644 apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
 create mode 100644 apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
 create mode 100644 packages/webkit/src/components/actions/copy-button/copy-button.vue
 create mode 100644 packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
 create mode 100644 packages/webkit/src/components/overlay/tooltip/package.json
 create mode 100644 packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
 create mode 100644 packages/webkit/src/components/overlay/tooltip/tooltip.figma.ts
 create mode 100644 packages/webkit/src/components/overlay/tooltip/tooltip.vue

diff --git a/.specs/copy-button.md b/.specs/copy-button.md
new file mode 100644
index 00000000..8b80b008
--- /dev/null
+++ b/.specs/copy-button.md
@@ -0,0 +1,114 @@
+---
+name: copy-button
+category: actions
+structure: monolithic
+status: approved
+spec_version: 1
+checksum: f3173c1d9c26f7a94e7c053f1a5fca826724244384859ff48fe263badbf6b0f0
+created: 2026-06-02
+last_updated: 2026-06-02
+---
+# Copy Button — Component Spec
+
+## Purpose
+
+Icon-only control that copies a string to the clipboard and briefly confirms success. Composes `IconButton` for visuals and interaction tokens.
+
+## Props
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `value` | `string` | `—` | yes | Text copied to the clipboard on activation. |
+| `ariaLabel` | `string` | `'Copy'` | no | Accessible name while idle. |
+| `copiedLabel` | `string` | `'Copied'` | no | Accessible name while the copied state is shown. |
+| `kind` | `'primary' \| 'secondary' \| 'outlined' \| 'transparent' \| 'danger'` | `'transparent'` | no | Visual variant forwarded to `IconButton`. |
+| `size` | `'small' \| 'medium' \| 'large'` | `'small'` | no | Size token forwarded to `IconButton`. |
+| `disabled` | `boolean` | `false` | no | Disables interaction and applies disabled tokens. |
+
+## Events
+
+| Event | Payload | Notes |
+|---|---|---|
+| `copy` | `string` | Emitted after a successful clipboard write with the copied value. |
+
+## Slots
+
+| _none_ | — | — |
+
+## States
+
+- Visual states: `default`, `copied`, `disabled`
+- `data-state` mirrors `default` or `copied`
+- `data-disabled` mirrors the `disabled` prop
+
+## Motion & Animations
+
+| Trigger | Animation / Transition | Token | Reduced-motion fallback |
+|---|---|---|---|
+| state change | `transition-colors duration-150 ease-out` (via `IconButton`) | inline | `motion-reduce:transition-none` |
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| typography | .text-button-lg |
+| surface | `var(--bg-surface)` |
+| text | `var(--text-default)` |
+| spacing | `var(--spacing-3)` |
+| shape | `var(--shape-elements)` |
+| ring | `var(--ring-color)` |
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| _none_ | — | — |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus: inherited from `IconButton` (`focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]`)
+- Keyboard map: `Tab` focuses; `Enter`/`Space` activates copy.
+- ARIA: `aria-label` toggles between `ariaLabel` and `copiedLabel` when copied.
+- Contrast ≥4.5:1 (text) / ≥3:1 (large + icons), including disabled state.
+- `motion-reduce:transition-none motion-reduce:transform-none` on animated states.
+- Touch target ≥40×40 px where the control is interactive.
+
+## Usage
+
+```vue
+<script setup>
+import CopyButton from '@aziontech/webkit/copy-button'
+</script>
+
+<template>
+  <CopyButton value="https://example.com/deploy/abc123" ariaLabel="Copy URL" />
+</template>
+```
+
+## Stories (Storybook)
+
+- Default
+- Disabled
+
+## Constraints — DO NOT
+
+<!-- This block is injected VERBATIM into every sub-agent prompt.
+     spec-validator rejects the spec if this block is missing or shorter than the template. -->
+
+- Do not add props beyond the Props table above. If you need a prop that is not listed, emit `BLOCKED: missing prop <name>` and stop — do not invent.
+- Do not add events beyond the Events table above. Same rule for slots and sub-components.
+- Do not invent imports. Every `@aziontech/webkit/*` path must exist in `packages/webkit/package.json#exports`. Every relative import must resolve to a real file. Every npm package must be installed.
+- Do not use HEX/RGB/HSL colors, Tailwind palette names (e.g. `bg-blue-500`), raw typography classes (e.g. `text-sm`), `any`, `@ts-ignore`, or `class` inside `defineProps`.
+- Do not install or import positioning/animation libraries (`@floating-ui/*`, `popper.js`, `tippy.js`, `gsap`, `framer-motion`, `motion`, `@vueuse/motion`, `@formkit/auto-animate`, drag-drop runtimes, scroll virtualization libs). Use CSS + Vue primitives (`<Teleport>`, `<Transition>`). See `.claude/rules/dependencies.md`.
+- Do not improvise animations. Every `animate-*` / `transition-*` class must come from `packages/theme/src/tokens/semantic/animations.js`; every motion-bearing class pairs with `motion-reduce:*` on the same class string; no component-local `@keyframes`.
+- Do not create class presets in JavaScript (`const kindClasses = {...}`, `const sharedClasses = [...]`, `const sizeClasses = {...}`, `const rootClasses = computed(...)`). Variants live on `data-*` attributes consumed by Tailwind `data-[attr=value]:`. All utilities live inline on the root element's `class` attribute. No `<style>` block, no component-local `.css`/`.scss`. See `.claude/rules/styling.md`.
+- Do not inherit artifacts as-is from another design system, Figma file, library, or pre-existing `CONTRACT.md` / `README.md`. Rewrite to our conventions. See `.claude/rules/migration.md`.
+- Do not add Figma references to Storybook stories. No `parameters.design`, no `parameters.figma`, no Figma URLs in `docs.description.*`, no `@storybook/addon-designs` import. The Figma link is owned by `<name>.figma.ts` (Code Connect). See `.claude/docs/COMPONENT_REQUIREMENTS.md`.
+- Do not use `parameters.actions.argTypesRegex` (deprecated in Storybook 8 and silently misroutes Vue 3 emits) or `parameters.actions.handles` (DOM-only). Declare every event explicitly in `argTypes` with a camelCase `on<Event>` key and `{ action: '<emitted-name>' }`. Do not use the legacy CSF2 `Name.args = {...}` form — always object-style CSF3.
+- Do not add bespoke Storybook stories beyond Default + per `kind` + per `size` + Disabled, unless the spec's "Stories (Storybook)" section explicitly justifies the addition.
+- Do not edit `.claude/docs/DESIGN.md`, `.claude/docs/COMPONENT_REQUIREMENTS.md`, or `.claude/docs/PRIMEVUE_ABSTRACTION.md`.
+- Do not edit the root `package.json` or `.github/workflows/*`.
+- Do not change `structure` after `status: approved`. To change structure, bump `spec_version` and re-author the spec.
+- Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
+- Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
+- If anything in the spec is ambiguous or contradicts the rules, emit `BLOCKED: <one-sentence reason>` and write nothing.
diff --git a/.specs/tooltip.md b/.specs/tooltip.md
new file mode 100644
index 00000000..b71a60c6
--- /dev/null
+++ b/.specs/tooltip.md
@@ -0,0 +1,131 @@
+---
+name: tooltip
+category: overlay
+structure: monolithic
+status: implemented
+spec_version: 1
+figma:
+  url: https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=4281-4543
+  node_id: 4281:4543
+checksum: b13da90c2c3e4c4965169d7174bd83fb0bfcaf1b437c35a03e47e4b53926a39e
+created: 2026-06-02
+last_updated: 2026-06-02
+---
+
+# Tooltip — Component Spec
+
+## Purpose
+
+Surfaces a short hint anchored to a trigger element when the user hovers, focuses, or long-presses it. Use for icon-only buttons, abbreviations, or any control whose meaning is not obvious from its label alone. **Not** for rich content or interactive children — use `overlay/popover` instead.
+
+## Usage
+
+```vue
+<script setup>
+import Tooltip from '@aziontech/webkit/overlay/tooltip'
+import IconButton from '@aziontech/webkit/icon-button'
+</script>
+
+<template>
+  <Tooltip text="Delete" placement="top">
+    <IconButton icon="pi pi-trash" aria-label="Delete" />
+  </Tooltip>
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Required | JSDoc |
+|---|---|---|---|---|
+| `text` | `string` | `''` | yes | Plain text shown inside the tooltip. |
+| `placement` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | no | Anchor side relative to the trigger. |
+| `delay` | `number` | `200` | no | Hover-open delay in milliseconds. |
+| `disabled` | `boolean` | `false` | no | Disables tooltip activation. |
+| `open` | `boolean` | `undefined` | no | Controlled open state. Use with `v-model:open`. |
+| `defaultOpen` | `boolean` | `false` | no | Initial open state when uncontrolled. |
+
+## Events
+
+| Event | Payload | Notes |
+|---|---|---|
+| `update:open` | `boolean` | v-model:open. Fires on open and close. |
+| `show` | `void` | Emitted right after the open transition starts. |
+| `hide` | `void` | Emitted right after the close transition starts. |
+
+## Slots
+
+| Slot | Scope | Notes |
+|---|---|---|
+| `default` | — | The trigger element. Tooltip anchors to its bounding box. |
+
+## States
+
+- Visual states: `default`, `hover`, `focus-visible`, `disabled`
+- `data-state` values: `open` | `closed`
+- `data-disabled` mirrors the `disabled` prop
+- `data-placement`: `top` | `right` | `bottom` | `left`
+
+## Motion & Animations
+
+| Trigger | Animation / Transition | Token | Reduced-motion fallback |
+|---|---|---|---|
+| open | `animate-popup-scale-in` | semantic (150ms · cubic-bezier) | `motion-reduce:animate-none` (instant) |
+| close | `animate-popup-scale-out` | semantic (110ms · cubic-bezier) | `motion-reduce:animate-none` (instant) |
+
+`--popup-origin` is set per instance based on `placement` (e.g. `top` → `bottom center`).
+
+## Tokens
+
+| Region | Token (DESIGN.md) |
+|---|---|
+| typography (label) | `.text-body-sm` |
+| surface | `var(--bg-surface)` |
+| text | `var(--text-default)` |
+| border | `var(--border-muted)` |
+| padding | `var(--spacing-xs)` |
+| max-width | `var(--container-3xs)` |
+| shape | `var(--shape-elements)` |
+| ring | `var(--ring-color)` |
+
+## Theme gaps
+
+| Figma variable | Temporary primitive | Follow-up |
+|---|---|---|
+| `bg-contrast` | `bg-[var(--bg-surface)]` | `TODO: tokenizar` (add `--bg-contrast` to DESIGN.md when contrast surface diverges) |
+| `text-contrast` | `text-[var(--text-default)]` | `TODO: tokenizar` (add `--text-contrast` to DESIGN.md when contrast text diverges) |
+
+## Accessibility (WCAG 2.1 AA)
+
+- Visible focus: `focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]` on the trigger wrapper.
+- Keyboard map: `Tab` focuses the trigger → tooltip opens; `Escape` closes; tooltip never traps focus.
+- ARIA: `role="tooltip"` on the panel; the trigger references the panel via `aria-describedby`. `aria-hidden="true"` when `data-state="closed"`.
+- Contrast ≥4.5:1 — text against surface verified in both light and dark modes.
+- `motion-reduce:animate-none` on the panel; reduced-motion users get instant show/hide.
+- Touch target ≥40×40 px on the trigger (the consumer's responsibility — flag in docs).
+
+## Stories (Storybook)
+
+- Default — tooltip rendered **closed**; viewer hovers/focuses the trigger to see it open.
+- Placements — composite story with all four placements (top/right/bottom/left) side-by-side; each instance defaults to **closed**.
+- Disabled — trigger present, tooltip activation no-op.
+
+## Constraints — DO NOT
+
+- Do not add props beyond the Props table above. If you need a prop that is not listed, emit `BLOCKED: missing prop <name>` and stop — do not invent.
+- Do not add events beyond the Events table above. Same rule for slots and sub-components.
+- Do not invent imports. Every `@aziontech/webkit/*` path must exist in `packages/webkit/package.json#exports`. Every relative import must resolve to a real file. Every npm package must be installed.
+- Do not use HEX/RGB/HSL colors, Tailwind palette names (e.g. `bg-blue-500`), raw typography classes (e.g. `text-sm`), `any`, `@ts-ignore`, or `class` inside `defineProps`.
+- Do not install or import positioning/animation libraries (`@floating-ui/*`, `popper.js`, `tippy.js`, `gsap`, `framer-motion`, `motion`, `@vueuse/motion`, `@formkit/auto-animate`, drag-drop runtimes, scroll virtualization libs). Use CSS + Vue primitives (`<Teleport>`, `<Transition>`). See `.claude/rules/dependencies.md`.
+- Do not improvise animations. Every `animate-*` / `transition-*` class must come from `packages/theme/src/tokens/semantic/animations.js`; every motion-bearing class pairs with `motion-reduce:*` on the same class string; no component-local `@keyframes`.
+- Do not create class presets in JavaScript (`const kindClasses = {...}`, `const sharedClasses = [...]`, `const sizeClasses = {...}`, `const rootClasses = computed(...)`). Variants live on `data-*` attributes consumed by Tailwind `data-[attr=value]:`. All utilities live inline on the root element's `class` attribute. No `<style>` block, no component-local `.css`/`.scss`. See `.claude/rules/styling.md`.
+- Do not inherit artifacts as-is from another design system, Figma file, library, or pre-existing `CONTRACT.md` / `README.md`. Rewrite to our conventions. See `.claude/rules/migration.md`.
+- Do not add Figma references to Storybook stories. No `parameters.design`, no `parameters.figma`, no Figma URLs in `docs.description.*`, no `@storybook/addon-designs` import. The Figma link is owned by `<name>.figma.ts` (Code Connect). See `.claude/docs/COMPONENT_REQUIREMENTS.md`.
+- Do not use `parameters.actions.argTypesRegex` (deprecated in Storybook 8 and silently misroutes Vue 3 emits) or `parameters.actions.handles` (DOM-only). Declare every event explicitly in `argTypes` with a camelCase `on<Event>` key and `{ action: '<emitted-name>' }`. Do not use the legacy CSF2 `Name.args = {...}` form — always object-style CSF3.
+- Do not add bespoke Storybook stories beyond Default + Types + Sizes + state stories (`Loading`, `Disabled`) for the props the component actually declares, unless the spec's "Stories (Storybook)" section explicitly justifies the addition. Do not split Types/Sizes into one-story-per-variant — the composite stories are the canonical pattern.
+- Do not duplicate the `## Usage` block from the spec inside the Storybook story body. The block is injected once into `parameters.docs.description.component` by the storybook-write skill; copy it nowhere else.
+- Do not edit `.claude/docs/DESIGN.md`, `.claude/docs/COMPONENT_REQUIREMENTS.md`, or `.claude/docs/PRIMEVUE_ABSTRACTION.md`.
+- Do not edit the root `package.json` or `.github/workflows/*`.
+- Do not change `structure` after `status: approved`. To change structure, bump `spec_version` and re-author the spec.
+- Do not create files outside the paths declared by your task (the orchestrator tells you exactly which files to write).
+- Do not run `git` commands, `pnpm install`, or any command that changes the lockfile.
+- If anything in the spec is ambiguous or contradicts the rules, emit `BLOCKED: <one-sentence reason>` and write nothing.
diff --git a/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js b/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
new file mode 100644
index 00000000..c12e16e2
--- /dev/null
+++ b/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
@@ -0,0 +1,108 @@
+import CopyButton from '@aziontech/webkit/copy-button'
+
+/** @type {import('@storybook/vue3').Meta<typeof CopyButton>} */
+const meta = {
+  title: 'Webkit/Actions/Copy Button',
+  component: CopyButton,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    backgrounds: {
+      default: 'dark'
+    },
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'focus-order-semantics', enabled: true }
+        ]
+      }
+    },
+    docs: {
+      description: {
+        component: `\`\`\`vue
+<script setup>
+import CopyButton from '@aziontech/webkit/copy-button'
+</script>
+
+<template>
+  <CopyButton value="https://example.com/deploy/abc123" ariaLabel="Copy URL" />
+</template>
+\`\`\``
+      }
+    }
+  },
+  argTypes: {
+    value: {
+      control: 'text',
+      description: 'Text copied to the clipboard on activation.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible name while idle.',
+      table: { category: 'props', type: { summary: 'string' }, defaultValue: { summary: "'Copy'" } }
+    },
+    copiedLabel: {
+      control: 'text',
+      description: 'Accessible name while the copied state is shown.',
+      table: { category: 'props', type: { summary: 'string' }, defaultValue: { summary: "'Copied'" } }
+    },
+    kind: {
+      control: 'select',
+      options: ['primary', 'secondary', 'outlined', 'transparent', 'danger'],
+      description: 'Visual variant forwarded to `IconButton`.',
+      table: {
+        category: 'props',
+        type: { summary: "'primary' | 'secondary' | 'outlined' | 'transparent' | 'danger'" },
+        defaultValue: { summary: "'transparent'" }
+      }
+    },
+    size: {
+      control: 'select',
+      options: ['small', 'medium', 'large'],
+      description: 'Size token forwarded to `IconButton`.',
+      table: {
+        category: 'props',
+        type: { summary: "'small' | 'medium' | 'large'" },
+        defaultValue: { summary: "'small'" }
+      }
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables interaction and applies disabled tokens.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    onCopy: {
+      action: 'copy',
+      description: 'Emitted after a successful clipboard write with the copied value.',
+      table: { category: 'events', type: { summary: 'string' } }
+    }
+  },
+  args: {
+    value: 'https://example.com/deploy/abc123',
+    ariaLabel: 'Copy URL',
+    copiedLabel: 'Copied',
+    kind: 'transparent',
+    size: 'small',
+    disabled: false
+  }
+}
+
+export default meta
+
+const Template = (args) => ({
+  components: { CopyButton },
+  setup() {
+    return { args }
+  },
+  template: '<CopyButton v-bind="args" @copy="args.onCopy" />'
+})
+
+/** @type {import('@storybook/vue3').StoryObj<typeof CopyButton>} */
+export const Default = {
+  render: Template,
+  parameters: {
+    docs: { description: { story: 'Default transparent copy button at small size.' } }
+  }
+}
diff --git a/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js b/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
new file mode 100644
index 00000000..511b2d3d
--- /dev/null
+++ b/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
@@ -0,0 +1,190 @@
+import Button from '@aziontech/webkit/button'
+import IconButton from '@aziontech/webkit/icon-button'
+import Tooltip from '@aziontech/webkit/overlay/tooltip'
+
+/** @type {import('@storybook/vue3').Meta<typeof Tooltip>} */
+const meta = {
+  title: 'Webkit/Overlay/Tooltip',
+  component: Tooltip,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    a11y: {
+      config: {
+        rules: [
+          { id: 'color-contrast', enabled: true },
+          { id: 'focus-order-semantics', enabled: true }
+        ]
+      }
+    },
+    docs: {
+      description: {
+        component: [
+          'Surfaces a short hint anchored to a trigger element when the user hovers, focuses, or long-presses it. Use for icon-only buttons, abbreviations, or any control whose meaning is not obvious from its label alone. **Not** for rich content or interactive children — use `overlay/popover` instead.',
+          '',
+          '## Usage',
+          '',
+          '```vue',
+          '<script setup>',
+          "import Tooltip from '@aziontech/webkit/overlay/tooltip'",
+          "import IconButton from '@aziontech/webkit/icon-button'",
+          '</script>',
+          '',
+          '<template>',
+          '  <Tooltip text="Delete" placement="top">',
+          '    <IconButton icon="pi pi-trash" aria-label="Delete" />',
+          '  </Tooltip>',
+          '</template>',
+          '```'
+        ].join('\n')
+      }
+    }
+  },
+  argTypes: {
+    text: {
+      control: 'text',
+      description: 'Plain text shown inside the tooltip.',
+      table: { category: 'props', type: { summary: 'string' } }
+    },
+    placement: {
+      control: 'select',
+      options: ['top', 'right', 'bottom', 'left'],
+      description: 'Anchor side relative to the trigger.',
+      table: {
+        category: 'props',
+        type: { summary: "'top' | 'right' | 'bottom' | 'left'" },
+        defaultValue: { summary: "'top'" }
+      }
+    },
+    delay: {
+      control: 'number',
+      description: 'Hover-open delay in milliseconds.',
+      table: { category: 'props', type: { summary: 'number' }, defaultValue: { summary: '200' } }
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables tooltip activation.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    open: {
+      control: 'boolean',
+      description: 'Controlled open state. Use with `v-model:open`.',
+      table: { category: 'props', type: { summary: 'boolean' } }
+    },
+    defaultOpen: {
+      control: 'boolean',
+      description: 'Initial open state when uncontrolled.',
+      table: { category: 'props', type: { summary: 'boolean' }, defaultValue: { summary: 'false' } }
+    },
+    onUpdateOpen: {
+      action: 'update:open',
+      description: 'v-model:open. Fires on open and close.',
+      table: { category: 'events', type: { summary: 'boolean' } }
+    },
+    onShow: {
+      action: 'show',
+      description: 'Emitted right after the open transition starts.',
+      table: { category: 'events', type: { summary: 'void' } }
+    },
+    onHide: {
+      action: 'hide',
+      description: 'Emitted right after the close transition starts.',
+      table: { category: 'events', type: { summary: 'void' } }
+    }
+  },
+  args: {
+    text: 'This is a Tooltip',
+    placement: 'top',
+    delay: 200,
+    disabled: false,
+    defaultOpen: false
+  }
+}
+
+export default meta
+
+const Template = (args) => ({
+  components: { Tooltip, Button },
+  setup() {
+    return { args }
+  },
+  template: `
+    <Tooltip
+      v-bind="args"
+      @update:open="args.onUpdateOpen"
+      @show="args.onShow"
+      @hide="args.onHide"
+    >
+      <Button label="Hover me" kind="outlined" size="medium" />
+    </Tooltip>
+  `
+})
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Tooltip>} */
+export const Default = {
+  render: Template,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Outlined button trigger. Hover or focus “Hover me” to reveal the tooltip.'
+      }
+    }
+  }
+}
+
+const placementIcons = {
+  top: 'pi pi-arrow-up',
+  right: 'pi pi-arrow-right',
+  bottom: 'pi pi-arrow-down',
+  left: 'pi pi-arrow-left'
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Tooltip>} */
+export const Placements = {
+  render: (args) => ({
+    components: { Tooltip, IconButton },
+    setup() {
+      const placements = ['top', 'right', 'bottom', 'left']
+      return { args, placements, placementIcons }
+    },
+    template: `
+      <div class="flex flex-wrap items-center justify-center gap-[var(--spacing-8)] p-[var(--spacing-8)]">
+        <Tooltip
+          v-for="placement in placements"
+          :key="placement"
+          v-bind="args"
+          :placement="placement"
+          :text="\`\${placement} placement\`"
+          @update:open="args.onUpdateOpen"
+          @show="args.onShow"
+          @hide="args.onHide"
+        >
+          <IconButton
+            :icon="placementIcons[placement]"
+            :aria-label="\`\${placement} placement\`"
+            kind="outlined"
+            size="medium"
+          />
+        </Tooltip>
+      </div>
+    `
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All four anchor sides with directional arrow triggers. Hover or focus each icon button to compare placement.'
+      }
+    }
+  }
+}
+
+/** @type {import('@storybook/vue3').StoryObj<typeof Tooltip>} */
+export const Disabled = {
+  render: Template,
+  args: {
+    disabled: true
+  },
+  parameters: {
+    docs: { description: { story: 'Tooltip activation is disabled; hover and focus have no effect.' } }
+  }
+}
diff --git a/packages/webkit/package.json b/packages/webkit/package.json
index cf751c63..de864a0f 100644
--- a/packages/webkit/package.json
+++ b/packages/webkit/package.json
@@ -94,6 +94,7 @@
     "./button-highlight": "./src/components/actions/button-highlight/button-highlight.vue",
     "./segmented-button": "./src/components/actions/segmented-button/segmented-button.vue",
     "./icon-button": "./src/components/actions/icon-button/icon-button.vue",
+    "./copy-button": "./src/components/actions/copy-button/copy-button.vue",
     "./button-cancel": "./src/components/wip/buttons/button-cancel/button-cancel.vue",
     "./button-clone": "./src/components/wip/buttons/button-clone/button-clone.vue",
     "./button-copy": "./src/components/wip/buttons/button-copy/button-copy.vue",
@@ -222,6 +223,7 @@
     "./overlay/dropdown-menu-separator": "./src/components/overlay/dropdown-menu/dropdown-menu-separator.vue",
     "./overlay/dropdown-menu-from-model": "./src/components/overlay/dropdown-menu/dropdown-menu-from-model.vue",
     "./overlay/dropdown-menu-factory": "./src/components/overlay/dropdown-menu/factory.ts",
+    "./overlay/tooltip": "./src/components/overlay/tooltip/tooltip.vue",
     "./templates/onboarding-form": "./src/components/templates/onboarding-form/onboarding-form.vue",
     "./templates/plan-success": "./src/components/templates/plan-success/plan-success.vue",
     "./templates/platform-shell": "./src/components/templates/platform-shell/platform-shell.vue",
diff --git a/packages/webkit/src/components/actions/copy-button/copy-button.vue b/packages/webkit/src/components/actions/copy-button/copy-button.vue
new file mode 100644
index 00000000..3a4f1381
--- /dev/null
+++ b/packages/webkit/src/components/actions/copy-button/copy-button.vue
@@ -0,0 +1,96 @@
+<script setup lang="ts">
+  import { computed, onBeforeUnmount, ref, useAttrs } from 'vue'
+
+  import type { IconButtonKind, IconButtonSize } from '../icon-button/icon-button.vue'
+  import IconButton from '../icon-button/icon-button.vue'
+
+  defineOptions({
+    name: 'CopyButton',
+    inheritAttrs: false
+  })
+
+  interface Props {
+    /** Text copied to the clipboard on activation. */
+    value: string
+    /** Accessible name while idle. */
+    ariaLabel?: string
+    /** Accessible name while the copied state is shown. */
+    copiedLabel?: string
+    /** Visual variant forwarded to `IconButton`. */
+    kind?: IconButtonKind
+    /** Size token forwarded to `IconButton`. */
+    size?: IconButtonSize
+    /** Disables interaction and applies disabled tokens. */
+    disabled?: boolean
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    ariaLabel: 'Copy',
+    copiedLabel: 'Copied',
+    kind: 'transparent',
+    size: 'small',
+    disabled: false
+  })
+
+  const emit = defineEmits<{
+    copy: [value: string]
+  }>()
+
+  const attrs = useAttrs()
+
+  const copied = ref(false)
+  let copiedTimeoutId: ReturnType<typeof setTimeout> | null = null
+
+  const testId = computed(
+    () => (attrs['data-testid'] as string | undefined) ?? 'actions-copy-button'
+  )
+
+  const icon = computed(() => (copied.value ? 'pi pi-check' : 'pi pi-copy'))
+  const label = computed(() => (copied.value ? props.copiedLabel : props.ariaLabel))
+  const iconClass = computed(() => (copied.value ? 'text-[var(--success-contrast)]' : undefined))
+
+  async function handleCopy(event: MouseEvent) {
+    if (props.disabled || !props.value || typeof globalThis.navigator === 'undefined') return
+
+    try {
+      await globalThis.navigator.clipboard.writeText(props.value)
+      copied.value = true
+      emit('copy', props.value)
+
+      if (copiedTimeoutId) {
+        clearTimeout(copiedTimeoutId)
+      }
+
+      copiedTimeoutId = setTimeout(() => {
+        copied.value = false
+        copiedTimeoutId = null
+      }, 2000)
+    } catch {
+      // Clipboard access may be denied; keep the idle state.
+    }
+
+    event.stopPropagation()
+  }
+
+  onBeforeUnmount(() => {
+    if (copiedTimeoutId) {
+      clearTimeout(copiedTimeoutId)
+    }
+  })
+</script>
+
+<template>
+  <IconButton
+    v-bind="attrs"
+    :icon="icon"
+    :iconClass="iconClass"
+    :ariaLabel="label"
+    :kind="kind"
+    :size="size"
+    :disabled="disabled"
+    iconTransition
+    :data-state="copied ? 'copied' : 'default'"
+    :data-testid="testId"
+    @click="handleCopy"
+  />
+</template>
diff --git a/packages/webkit/src/components/actions/icon-button/icon-button.vue b/packages/webkit/src/components/actions/icon-button/icon-button.vue
index 25a5043b..887941f9 100644
--- a/packages/webkit/src/components/actions/icon-button/icon-button.vue
+++ b/packages/webkit/src/components/actions/icon-button/icon-button.vue
@@ -1,7 +1,15 @@
 <script setup lang="ts">
-  import { computed, useAttrs } from 'vue'
+  import { computed, Transition, useAttrs } from 'vue'
 
   import Spinner from '../../utils/spinner/spinner.vue'
+  import {
+    iconTransitionEnterActiveClasses,
+    iconTransitionEnterFromClasses,
+    iconTransitionEnterToClasses,
+    iconTransitionLeaveActiveClasses,
+    iconTransitionLeaveFromClasses,
+    iconTransitionLeaveToClasses
+  } from './presets/icon-transition.js'
 
   export type IconButtonKind = 'primary' | 'secondary' | 'outlined' | 'transparent' | 'danger'
   export type IconButtonSize = 'small' | 'medium' | 'large'
@@ -9,7 +17,8 @@
 
   defineOptions({
     name: 'IconButton',
-    inheritAttrs: false
+    inheritAttrs: false,
+    components: { Transition }
   })
 
   interface Props {
@@ -29,6 +38,10 @@
     href?: string
     /** Link target when `href` is set. */
     target?: IconButtonTarget
+    /** Animates icon swaps with enter/leave transitions. */
+    iconTransition?: boolean
+    /** Extra classes applied to the icon glyph. */
+    iconClass?: string
   }
 
   const props = withDefaults(defineProps<Props>(), {
@@ -37,7 +50,9 @@
     disabled: false,
     loading: false,
     href: '',
-    target: '_self'
+    target: '_self',
+    iconTransition: false,
+    iconClass: ''
   })
 
   const emit = defineEmits<{
@@ -90,6 +105,10 @@
   const disabledClasses =
     'pointer-events-none cursor-not-allowed border-transparent bg-[var(--bg-disabled)] text-[var(--text-disabled)] before:hidden after:hidden'
 
+  const iconClasses =
+    'inline-flex shrink-0 items-center justify-center text-[length:inherit] leading-none'
+  const iconHostClasses = 'relative z-[1] inline-flex size-[1em] items-center justify-center'
+
   const sizeClasses: Record<IconButtonSize, string> = {
     large: 'size-10 text-button-lg',
     medium: 'size-8 text-button-md',
@@ -136,16 +155,31 @@
     :data-testid="testId"
     @click="handleClick"
   >
-    <span class="relative z-[1] inline-flex items-center justify-center">
+    <span :class="iconHostClasses">
       <Spinner
         v-if="loading"
         :class="spinnerSizeClasses[size]"
         :data-testid="loadingTestId"
       />
+      <Transition
+        v-else-if="iconTransition"
+        mode="out-in"
+        :enter-active-class="iconTransitionEnterActiveClasses"
+        :enter-from-class="iconTransitionEnterFromClasses"
+        :enter-to-class="iconTransitionEnterToClasses"
+        :leave-active-class="iconTransitionLeaveActiveClasses"
+        :leave-from-class="iconTransitionLeaveFromClasses"
+        :leave-to-class="iconTransitionLeaveToClasses"
+      >
+        <i
+          :key="icon"
+          :class="[icon, iconClasses, iconClass]"
+          aria-hidden="true"
+        />
+      </Transition>
       <i
         v-else
-        :class="icon"
-        class="shrink-0 text-[length:inherit] leading-none"
+        :class="[icon, iconClasses, iconClass]"
         aria-hidden="true"
       />
     </span>
@@ -163,16 +197,31 @@
     :data-testid="testId"
     @click="handleClick"
   >
-    <span class="relative z-[1] inline-flex items-center justify-center">
+    <span :class="iconHostClasses">
       <Spinner
         v-if="loading"
         :class="spinnerSizeClasses[size]"
         :data-testid="loadingTestId"
       />
+      <Transition
+        v-else-if="iconTransition"
+        mode="out-in"
+        :enter-active-class="iconTransitionEnterActiveClasses"
+        :enter-from-class="iconTransitionEnterFromClasses"
+        :enter-to-class="iconTransitionEnterToClasses"
+        :leave-active-class="iconTransitionLeaveActiveClasses"
+        :leave-from-class="iconTransitionLeaveFromClasses"
+        :leave-to-class="iconTransitionLeaveToClasses"
+      >
+        <i
+          :key="icon"
+          :class="[icon, iconClasses, iconClass]"
+          aria-hidden="true"
+        />
+      </Transition>
       <i
         v-else
-        :class="icon"
-        class="shrink-0 text-[length:inherit] leading-none"
+        :class="[icon, iconClasses, iconClass]"
         aria-hidden="true"
       />
     </span>
diff --git a/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js b/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
new file mode 100644
index 00000000..76bd8f7c
--- /dev/null
+++ b/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
@@ -0,0 +1,24 @@
+/**
+ * Icon swap motion — timing from `animate.js` (`moderate-01`/`productive-entrance` enter,
+ * `fast-02`/`productive-exit` leave).
+ */
+
+export const iconTransitionEnterActiveClasses = [
+  'transition-[transform,opacity] duration-moderate-01 ease-productive-entrance',
+  'motion-reduce:transition-none motion-reduce:transform-none'
+].join(' ')
+
+export const iconTransitionEnterFromClasses =
+  'scale-0 opacity-0 motion-reduce:scale-100 motion-reduce:opacity-100'
+
+export const iconTransitionEnterToClasses = 'scale-100 opacity-100'
+
+export const iconTransitionLeaveActiveClasses = [
+  'pointer-events-none absolute inset-0 inline-flex items-center justify-center',
+  'transition-opacity duration-fast-02 ease-productive-exit',
+  'motion-reduce:transition-none'
+].join(' ')
+
+export const iconTransitionLeaveFromClasses = 'opacity-100'
+
+export const iconTransitionLeaveToClasses = 'opacity-0'
diff --git a/packages/webkit/src/components/overlay/tooltip/package.json b/packages/webkit/src/components/overlay/tooltip/package.json
new file mode 100644
index 00000000..36b0317a
--- /dev/null
+++ b/packages/webkit/src/components/overlay/tooltip/package.json
@@ -0,0 +1,11 @@
+{
+  "main": "./tooltip.vue",
+  "module": "./tooltip.vue",
+  "types": "./tooltip.vue.d.ts",
+  "browser": {
+    "./sfc": "./tooltip.vue"
+  },
+  "sideEffects": [
+    "*.vue"
+  ]
+}
diff --git a/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
new file mode 100644
index 00000000..04c8ac95
--- /dev/null
+++ b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
@@ -0,0 +1,31 @@
+/**
+ * Popup scale motion (0.95 → 1, opacity 0 → 1) — timing from `animate.js`
+ * (`moderate-01` / `productive-entrance` enter, `fast-02` / `productive-exit` leave).
+ * Spec also lists `animate-popup-scale-in` / `animate-popup-scale-out` (semantic keyframes).
+ */
+
+export const popupScaleTransitionEnterActiveClasses = [
+  'transition-[transform,opacity]',
+  'duration-moderate-01',
+  'ease-productive-entrance',
+  'motion-reduce:transition-none',
+  'motion-reduce:transform-none'
+].join(' ')
+
+export const popupScaleTransitionEnterFromClasses =
+  'scale-[0.95] opacity-0 motion-reduce:scale-100 motion-reduce:opacity-100'
+
+export const popupScaleTransitionEnterToClasses = 'scale-100 opacity-100'
+
+export const popupScaleTransitionLeaveActiveClasses = [
+  'transition-[transform,opacity]',
+  'duration-fast-02',
+  'ease-productive-exit',
+  'motion-reduce:transition-none',
+  'motion-reduce:transform-none'
+].join(' ')
+
+export const popupScaleTransitionLeaveFromClasses = 'scale-100 opacity-100'
+
+export const popupScaleTransitionLeaveToClasses =
+  'scale-[0.95] opacity-0 motion-reduce:scale-100 motion-reduce:opacity-100'
diff --git a/packages/webkit/src/components/overlay/tooltip/tooltip.figma.ts b/packages/webkit/src/components/overlay/tooltip/tooltip.figma.ts
new file mode 100644
index 00000000..c5ec8085
--- /dev/null
+++ b/packages/webkit/src/components/overlay/tooltip/tooltip.figma.ts
@@ -0,0 +1,18 @@
+import { figma } from '@figma/code-connect'
+
+import Tooltip from './tooltip.vue'
+
+figma.connect(
+  Tooltip,
+  'https://www.figma.com/design/t97pXRs7xME3SJDs5iZ5RF/Webkit?node-id=4281-4543',
+  {
+    props: {
+      text: figma.string('label')
+    },
+    example: ({ text }) => /* html */ `
+    <Tooltip text="${text}">
+      <IconButton icon="pi pi-info-circle" aria-label="More information" />
+    </Tooltip>
+  `
+  }
+)
diff --git a/packages/webkit/src/components/overlay/tooltip/tooltip.vue b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
new file mode 100644
index 00000000..74a42745
--- /dev/null
+++ b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
@@ -0,0 +1,291 @@
+<script setup lang="ts">
+  import { computed, nextTick, onBeforeUnmount, onMounted, ref, useAttrs, useId, watch } from 'vue'
+
+  import { useControllable } from '../../../composables/use-controllable'
+  import {
+    popupScaleTransitionEnterActiveClasses,
+    popupScaleTransitionEnterFromClasses,
+    popupScaleTransitionEnterToClasses,
+    popupScaleTransitionLeaveActiveClasses,
+    popupScaleTransitionLeaveFromClasses,
+    popupScaleTransitionLeaveToClasses
+  } from './presets/popup-scale-transition.js'
+
+  // Motion utilities (spec): animate-popup-scale-in, animate-popup-scale-out
+
+  export type TooltipPlacement = 'top' | 'right' | 'bottom' | 'left'
+
+  defineOptions({
+    name: 'Tooltip',
+    inheritAttrs: false
+  })
+
+  defineSlots<{
+    default(): unknown
+  }>()
+
+  interface Props {
+    /** Plain text shown inside the tooltip. */
+    text: string
+    /** Anchor side relative to the trigger. */
+    placement?: TooltipPlacement
+    /** Hover-open delay in milliseconds. */
+    delay?: number
+    /** Disables tooltip activation. */
+    disabled?: boolean
+    /** Controlled open state. Use with `v-model:open`. */
+    open?: boolean
+    /** Initial open state when uncontrolled. */
+    defaultOpen?: boolean
+  }
+
+  const props = withDefaults(defineProps<Props>(), {
+    placement: 'top',
+    delay: 200,
+    disabled: false,
+    open: undefined,
+    defaultOpen: false
+  })
+
+  const emit = defineEmits<{
+    'update:open': [value: boolean]
+    show: []
+    hide: []
+  }>()
+
+  const openModel = defineModel<boolean>('open', { default: undefined })
+
+  const attrs = useAttrs()
+  const uid = useId()
+  const triggerRef = ref<HTMLElement | null>(null)
+  const panelRef = ref<HTMLElement | null>(null)
+  const panelStyle = ref<Record<string, string>>({})
+  const hoverTimer = ref<ReturnType<typeof setTimeout> | null>(null)
+  const resolvedPlacement = ref<TooltipPlacement>(props.placement)
+
+  const testId = computed(() => (attrs['data-testid'] as string | undefined) ?? 'overlay-tooltip')
+
+  const tooltipId = computed(() => `${uid}-tooltip`)
+
+  const openProp = computed(() => openModel.value ?? props.open)
+
+  const isOpen = useControllable({
+    prop: openProp,
+    defaultProp: props.defaultOpen,
+    onChange: (value) => {
+      openModel.value = value
+      emit('update:open', value)
+    }
+  })
+
+  function getPopupOrigin(side: TooltipPlacement): string {
+    if (side === 'top') return 'bottom center'
+    if (side === 'bottom') return 'top center'
+    if (side === 'left') return 'right center'
+    return 'left center'
+  }
+
+  function clearHoverTimer() {
+    if (hoverTimer.value) {
+      clearTimeout(hoverTimer.value)
+      hoverTimer.value = null
+    }
+  }
+
+  function setOpen(next: boolean) {
+    if (props.disabled) return
+    if (!props.text && next) return
+    isOpen.set(next)
+  }
+
+  function scheduleOpen() {
+    if (props.disabled || !props.text) return
+    clearHoverTimer()
+    hoverTimer.value = setTimeout(() => setOpen(true), props.delay)
+  }
+
+  function closeTooltip() {
+    clearHoverTimer()
+    setOpen(false)
+  }
+
+  function updatePosition() {
+    const trigger = triggerRef.value
+    const panel = panelRef.value
+
+    if (!trigger || !panel) {
+      panelStyle.value = {}
+      return
+    }
+
+    const triggerRect = trigger.getBoundingClientRect()
+    const panelRect = panel.getBoundingClientRect()
+    const offset = 8
+    const collisionPadding = 8
+    const viewport = {
+      width: globalThis.innerWidth ?? 0,
+      height: globalThis.innerHeight ?? 0
+    }
+
+    const opposite: Record<TooltipPlacement, TooltipPlacement> = {
+      top: 'bottom',
+      bottom: 'top',
+      left: 'right',
+      right: 'left'
+    }
+
+    const fits = (candidate: TooltipPlacement) => {
+      switch (candidate) {
+        case 'bottom':
+          return (
+            triggerRect.bottom + offset + panelRect.height + collisionPadding <= viewport.height
+          )
+        case 'top':
+          return triggerRect.top - offset - panelRect.height - collisionPadding >= 0
+        case 'right':
+          return triggerRect.right + offset + panelRect.width + collisionPadding <= viewport.width
+        case 'left':
+          return triggerRect.left - offset - panelRect.width - collisionPadding >= 0
+        default:
+          return true
+      }
+    }
+
+    let side: TooltipPlacement = props.placement
+    if (!fits(side) && fits(opposite[side])) {
+      side = opposite[side]
+    }
+    resolvedPlacement.value = side
+
+    let top = 0
+    let left = 0
+
+    if (side === 'top') {
+      top = triggerRect.top - panelRect.height - offset
+      left = triggerRect.left + triggerRect.width / 2 - panelRect.width / 2
+    } else if (side === 'bottom') {
+      top = triggerRect.bottom + offset
+      left = triggerRect.left + triggerRect.width / 2 - panelRect.width / 2
+    } else if (side === 'left') {
+      top = triggerRect.top + triggerRect.height / 2 - panelRect.height / 2
+      left = triggerRect.left - panelRect.width - offset
+    } else {
+      top = triggerRect.top + triggerRect.height / 2 - panelRect.height / 2
+      left = triggerRect.right + offset
+    }
+
+    const maxLeft = viewport.width - panelRect.width - collisionPadding
+    const maxTop = viewport.height - panelRect.height - collisionPadding
+    left = Math.min(Math.max(left, collisionPadding), Math.max(collisionPadding, maxLeft))
+    top = Math.min(Math.max(top, collisionPadding), Math.max(collisionPadding, maxTop))
+
+    panelStyle.value = {
+      position: 'fixed',
+      top: `${top}px`,
+      left: `${left}px`,
+      zIndex: '1100',
+      '--popup-origin': getPopupOrigin(side)
+    }
+  }
+
+  function onDocumentKeydown(event: globalThis.KeyboardEvent) {
+    if (!isOpen.value) return
+    if (event.key === 'Escape') {
+      event.preventDefault()
+      closeTooltip()
+    }
+  }
+
+  function onScrollOrResize() {
+    if (!isOpen.value) return
+    updatePosition()
+  }
+
+  function onFocusOut(event: globalThis.FocusEvent) {
+    const trigger = triggerRef.value
+    const next = event.relatedTarget as Node | null
+    if (trigger?.contains(next)) return
+    closeTooltip()
+  }
+
+  watch(
+    () => isOpen.value,
+    async (open) => {
+      if (!open) return
+      await nextTick()
+      updatePosition()
+      await nextTick()
+      updatePosition()
+    }
+  )
+
+  watch(
+    () => props.placement,
+    () => {
+      resolvedPlacement.value = props.placement
+      if (isOpen.value) {
+        nextTick(() => updatePosition())
+      }
+    }
+  )
+
+  onMounted(() => {
+    globalThis.document?.addEventListener('keydown', onDocumentKeydown)
+    globalThis.window?.addEventListener('resize', onScrollOrResize)
+    globalThis.document?.addEventListener('scroll', onScrollOrResize, true)
+  })
+
+  onBeforeUnmount(() => {
+    clearHoverTimer()
+    globalThis.document?.removeEventListener('keydown', onDocumentKeydown)
+    globalThis.window?.removeEventListener('resize', onScrollOrResize)
+    globalThis.document?.removeEventListener('scroll', onScrollOrResize, true)
+  })
+</script>
+
+<template>
+  <span
+    ref="triggerRef"
+    v-bind="attrs"
+    class="inline-flex focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]"
+    :data-testid="testId"
+    :data-state="isOpen ? 'open' : 'closed'"
+    :data-disabled="disabled || null"
+    :data-placement="resolvedPlacement"
+    :aria-describedby="isOpen && text ? tooltipId : undefined"
+    @mouseenter="scheduleOpen"
+    @mouseleave="closeTooltip"
+    @focusin="setOpen(true)"
+    @focusout="onFocusOut"
+  >
+    <slot />
+  </span>
+
+  <Teleport to="body">
+    <Transition
+      :enter-active-class="popupScaleTransitionEnterActiveClasses"
+      :enter-from-class="popupScaleTransitionEnterFromClasses"
+      :enter-to-class="popupScaleTransitionEnterToClasses"
+      :leave-active-class="popupScaleTransitionLeaveActiveClasses"
+      :leave-from-class="popupScaleTransitionLeaveFromClasses"
+      :leave-to-class="popupScaleTransitionLeaveToClasses"
+      @before-enter="emit('show')"
+      @before-leave="emit('hide')"
+    >
+      <div
+        v-if="isOpen && text"
+        :id="tooltipId"
+        ref="panelRef"
+        role="tooltip"
+        :data-testid="`${testId}__panel`"
+        :data-state="isOpen ? 'open' : 'closed'"
+        :data-placement="resolvedPlacement"
+        :aria-hidden="!isOpen"
+        :style="panelStyle"
+        class="pointer-events-none flex min-h-8 max-w-[var(--container-3xs)] items-center justify-center overflow-clip break-words rounded-[var(--shape-elements)] border border-[var(--border-muted)] bg-[var(--bg-contrast)] p-[var(--spacing-xs)] text-center text-body-sm text-[var(--text-contrast)] [transform-origin:var(--popup-origin,center)] will-change-[transform,opacity]"
+      >
+        {{ text }}
+      </div>
+    </Transition>
+  </Teleport>
+</template>

From 0de0004abaac125bac9f1a2c9ba0307bfa793dc9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Wed, 3 Jun 2026 15:39:43 -0300
Subject: [PATCH 2/4] feat(theme): add text-contrast token for Tooltip surface

---
 packages/theme/dist/v3/globals.css      |  2 ++
 packages/theme/dist/v3/globals.scss     |  2 ++
 packages/theme/src/tokens/theme/text.js | 10 ++++++----
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/packages/theme/dist/v3/globals.css b/packages/theme/dist/v3/globals.css
index b9ae7d56..fc41aae0 100644
--- a/packages/theme/dist/v3/globals.css
+++ b/packages/theme/dist/v3/globals.css
@@ -707,6 +707,7 @@
   --text-muted: #666666;
   --text-disabled: #999999;
   --text-link: #005FCC;
+  --text-contrast: #FAFAFA;
   --ring-color: #0A0A0A;
   --success: #F0FDF4;
   --success-border: #22C55E99;
@@ -766,6 +767,7 @@
   --text-muted: #999999;
   --text-disabled: #4D4D4D;
   --text-link: #3392FF;
+  --text-contrast: #141414;
   --ring-color: #FFFFFF;
   --success: #03170B;
   --success-border: #22C55E66;
diff --git a/packages/theme/dist/v3/globals.scss b/packages/theme/dist/v3/globals.scss
index b9ae7d56..fc41aae0 100644
--- a/packages/theme/dist/v3/globals.scss
+++ b/packages/theme/dist/v3/globals.scss
@@ -707,6 +707,7 @@
   --text-muted: #666666;
   --text-disabled: #999999;
   --text-link: #005FCC;
+  --text-contrast: #FAFAFA;
   --ring-color: #0A0A0A;
   --success: #F0FDF4;
   --success-border: #22C55E99;
@@ -766,6 +767,7 @@
   --text-muted: #999999;
   --text-disabled: #4D4D4D;
   --text-link: #3392FF;
+  --text-contrast: #141414;
   --ring-color: #FFFFFF;
   --success: #03170B;
   --success-border: #22C55E66;
diff --git a/packages/theme/src/tokens/theme/text.js b/packages/theme/src/tokens/theme/text.js
index d50dda7b..64596658 100644
--- a/packages/theme/src/tokens/theme/text.js
+++ b/packages/theme/src/tokens/theme/text.js
@@ -1,4 +1,4 @@
-import { tokenRef } from '../../scripts/refs.js';
+import { tokenRef } from '../../scripts/refs.js'
 
 export const text = {
   light: {
@@ -6,13 +6,15 @@ export const text = {
     'text-muted': tokenRef('primitives.gray.600'),
     'text-disabled': tokenRef('primitives.gray.400'),
     'text-link': tokenRef('primitives.blue.600'),
+    'text-contrast': tokenRef('primitives.gray.50')
   },
   dark: {
     'text-default': tokenRef('primitives.gray.50'),
     'text-muted': tokenRef('primitives.gray.400'),
     'text-disabled': tokenRef('primitives.gray.700'),
     'text-link': tokenRef('primitives.blue.400'),
-  },
-};
+    'text-contrast': tokenRef('primitives.gray.900')
+  }
+}
 
-export default { text };
+export default { text }

From 95cb7e30ef59dc9b6a6a2f5e95f527e941087c4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Wed, 3 Jun 2026 16:22:50 -0300
Subject: [PATCH 3/4] feat(copy-button): integrate Tooltip and stabilize icon
 swap motion

CopyButton uses Tooltip for hover/focus and post-copy feedback with outlined as default; IconButton and Tooltip presets avoid layout shift and align motion with theme tokens.
---
 .../actions/copy-button/CopyButton.stories.js |  6 +--
 .../actions/copy-button/copy-button.vue       | 37 ++++++++++++-------
 .../actions/icon-button/icon-button.vue       | 29 +++++++++++----
 .../icon-button/presets/icon-transition.js    | 15 +++++++-
 .../tooltip/presets/popup-scale-transition.js | 19 ++++++++--
 .../components/overlay/tooltip/tooltip.vue    | 15 ++++++--
 6 files changed, 89 insertions(+), 32 deletions(-)

diff --git a/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js b/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
index c12e16e2..affe2ca4 100644
--- a/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
+++ b/apps/storybook/src/stories/webkit/actions/copy-button/CopyButton.stories.js
@@ -55,7 +55,7 @@ import CopyButton from '@aziontech/webkit/copy-button'
       table: {
         category: 'props',
         type: { summary: "'primary' | 'secondary' | 'outlined' | 'transparent' | 'danger'" },
-        defaultValue: { summary: "'transparent'" }
+        defaultValue: { summary: "'outlined'" }
       }
     },
     size: {
@@ -83,7 +83,7 @@ import CopyButton from '@aziontech/webkit/copy-button'
     value: 'https://example.com/deploy/abc123',
     ariaLabel: 'Copy URL',
     copiedLabel: 'Copied',
-    kind: 'transparent',
+    kind: 'outlined',
     size: 'small',
     disabled: false
   }
@@ -103,6 +103,6 @@ const Template = (args) => ({
 export const Default = {
   render: Template,
   parameters: {
-    docs: { description: { story: 'Default transparent copy button at small size.' } }
+    docs: { description: { story: 'Outlined copy button with hover/focus tooltip at small size.' } }
   }
 }
diff --git a/packages/webkit/src/components/actions/copy-button/copy-button.vue b/packages/webkit/src/components/actions/copy-button/copy-button.vue
index 3a4f1381..1bee8f29 100644
--- a/packages/webkit/src/components/actions/copy-button/copy-button.vue
+++ b/packages/webkit/src/components/actions/copy-button/copy-button.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
   import { computed, onBeforeUnmount, ref, useAttrs } from 'vue'
 
+  import Tooltip from '../../overlay/tooltip/tooltip.vue'
   import type { IconButtonKind, IconButtonSize } from '../icon-button/icon-button.vue'
   import IconButton from '../icon-button/icon-button.vue'
 
@@ -27,7 +28,7 @@
   const props = withDefaults(defineProps<Props>(), {
     ariaLabel: 'Copy',
     copiedLabel: 'Copied',
-    kind: 'transparent',
+    kind: 'outlined',
     size: 'small',
     disabled: false
   })
@@ -39,6 +40,7 @@
   const attrs = useAttrs()
 
   const copied = ref(false)
+  const tooltipOpen = ref<boolean | undefined>(undefined)
   let copiedTimeoutId: ReturnType<typeof setTimeout> | null = null
 
   const testId = computed(
@@ -55,6 +57,7 @@
     try {
       await globalThis.navigator.clipboard.writeText(props.value)
       copied.value = true
+      tooltipOpen.value = true
       emit('copy', props.value)
 
       if (copiedTimeoutId) {
@@ -63,6 +66,7 @@
 
       copiedTimeoutId = setTimeout(() => {
         copied.value = false
+        tooltipOpen.value = false
         copiedTimeoutId = null
       }, 2000)
     } catch {
@@ -80,17 +84,24 @@
 </script>
 
 <template>
-  <IconButton
-    v-bind="attrs"
-    :icon="icon"
-    :iconClass="iconClass"
-    :ariaLabel="label"
-    :kind="kind"
-    :size="size"
+  <Tooltip
+    v-model:open="tooltipOpen"
+    :text="label"
     :disabled="disabled"
-    iconTransition
-    :data-state="copied ? 'copied' : 'default'"
-    :data-testid="testId"
-    @click="handleCopy"
-  />
+    :data-testid="`${testId}__tooltip`"
+  >
+    <IconButton
+      v-bind="attrs"
+      :icon="icon"
+      :iconClass="iconClass"
+      :ariaLabel="label"
+      :kind="kind"
+      :size="size"
+      :disabled="disabled"
+      iconTransition
+      :data-state="copied ? 'copied' : 'default'"
+      :data-testid="testId"
+      @click="handleCopy"
+    />
+  </Tooltip>
 </template>
diff --git a/packages/webkit/src/components/actions/icon-button/icon-button.vue b/packages/webkit/src/components/actions/icon-button/icon-button.vue
index 887941f9..73b09a28 100644
--- a/packages/webkit/src/components/actions/icon-button/icon-button.vue
+++ b/packages/webkit/src/components/actions/icon-button/icon-button.vue
@@ -6,6 +6,8 @@
     iconTransitionEnterActiveClasses,
     iconTransitionEnterFromClasses,
     iconTransitionEnterToClasses,
+    iconTransitionHostClasses,
+    iconTransitionIconClasses,
     iconTransitionLeaveActiveClasses,
     iconTransitionLeaveFromClasses,
     iconTransitionLeaveToClasses
@@ -95,7 +97,7 @@
     secondary:
       'bg-[var(--secondary)] text-[var(--secondary-contrast)] before:bg-[var(--bg-hover)] after:bg-[var(--bg-active)]',
     outlined:
-      'border border-[var(--border-muted)] bg-[var(--bg-surface)] text-[var(--text-default)] before:bg-[var(--bg-mask)] after:bg-[var(--bg-active)]',
+      'border border-[var(--border-default)] bg-[var(--bg-surface)] text-[var(--text-default)] before:bg-[var(--bg-mask)] after:bg-[var(--bg-active)]',
     transparent:
       'bg-transparent text-[var(--text-default)] before:bg-[var(--bg-mask)] after:bg-[var(--bg-active)]',
     danger:
@@ -107,7 +109,6 @@
 
   const iconClasses =
     'inline-flex shrink-0 items-center justify-center text-[length:inherit] leading-none'
-  const iconHostClasses = 'relative z-[1] inline-flex size-[1em] items-center justify-center'
 
   const sizeClasses: Record<IconButtonSize, string> = {
     large: 'size-10 text-button-lg',
@@ -115,12 +116,14 @@
     small: 'size-7 text-button-md'
   }
 
-  const spinnerSizeClasses: Record<IconButtonSize, string> = {
+  const iconSlotSizeClasses: Record<IconButtonSize, string> = {
     large: 'size-4',
     medium: 'size-3',
     small: 'size-3'
   }
 
+  const spinnerSizeClasses = iconSlotSizeClasses
+
   const rootClasses = computed(() => {
     const kind = props.disabled ? disabledClasses : kindClasses[props.kind]
     const loadingClasses = props.loading && !props.disabled ? 'cursor-loading' : ''
@@ -155,7 +158,13 @@
     :data-testid="testId"
     @click="handleClick"
   >
-    <span :class="iconHostClasses">
+    <span
+      :class="
+        iconTransition
+          ? [iconTransitionHostClasses, iconSlotSizeClasses[size]]
+          : 'relative z-[1] inline-flex items-center justify-center'
+      "
+    >
       <Spinner
         v-if="loading"
         :class="spinnerSizeClasses[size]"
@@ -173,7 +182,7 @@
       >
         <i
           :key="icon"
-          :class="[icon, iconClasses, iconClass]"
+          :class="[icon, iconClasses, iconTransitionIconClasses, iconClass]"
           aria-hidden="true"
         />
       </Transition>
@@ -197,7 +206,13 @@
     :data-testid="testId"
     @click="handleClick"
   >
-    <span :class="iconHostClasses">
+    <span
+      :class="
+        iconTransition
+          ? [iconTransitionHostClasses, iconSlotSizeClasses[size]]
+          : 'relative z-[1] inline-flex items-center justify-center'
+      "
+    >
       <Spinner
         v-if="loading"
         :class="spinnerSizeClasses[size]"
@@ -215,7 +230,7 @@
       >
         <i
           :key="icon"
-          :class="[icon, iconClasses, iconClass]"
+          :class="[icon, iconClasses, iconTransitionIconClasses, iconClass]"
           aria-hidden="true"
         />
       </Transition>
diff --git a/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js b/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
index 76bd8f7c..98fe805a 100644
--- a/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
+++ b/packages/webkit/src/components/actions/icon-button/presets/icon-transition.js
@@ -1,9 +1,13 @@
 /**
  * Icon swap motion — timing from `animate.js` (`moderate-01`/`productive-entrance` enter,
- * `fast-02`/`productive-exit` leave).
+ * `fast-02`/`productive-exit` leave). Enter/leave glyphs stay centered in the host box.
  */
 
+const iconTransitionLayerClasses =
+  'pointer-events-none absolute inset-0 inline-flex items-center justify-center'
+
 export const iconTransitionEnterActiveClasses = [
+  iconTransitionLayerClasses,
   'transition-[transform,opacity] duration-moderate-01 ease-productive-entrance',
   'motion-reduce:transition-none motion-reduce:transform-none'
 ].join(' ')
@@ -14,7 +18,7 @@ export const iconTransitionEnterFromClasses =
 export const iconTransitionEnterToClasses = 'scale-100 opacity-100'
 
 export const iconTransitionLeaveActiveClasses = [
-  'pointer-events-none absolute inset-0 inline-flex items-center justify-center',
+  iconTransitionLayerClasses,
   'transition-opacity duration-fast-02 ease-productive-exit',
   'motion-reduce:transition-none'
 ].join(' ')
@@ -22,3 +26,10 @@ export const iconTransitionLeaveActiveClasses = [
 export const iconTransitionLeaveFromClasses = 'opacity-100'
 
 export const iconTransitionLeaveToClasses = 'opacity-0'
+
+/** Fixed box for swap motion; width/height come from IconButton size tokens. */
+export const iconTransitionHostClasses =
+  'relative z-[1] inline-flex shrink-0 items-center justify-center overflow-hidden'
+
+/** Keeps glyphs out of flow so copy/check metrics cannot resize the button. */
+export const iconTransitionIconClasses = iconTransitionLayerClasses
diff --git a/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
index 04c8ac95..f30caf9d 100644
--- a/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
+++ b/packages/webkit/src/components/overlay/tooltip/presets/popup-scale-transition.js
@@ -1,9 +1,22 @@
+import {
+  curve,
+  duration
+} from '../../../../../../theme/src/tokens/primitives/animations/animate.js'
+
 /**
- * Popup scale motion (0.95 → 1, opacity 0 → 1) — timing from `animate.js`
- * (`moderate-01` / `productive-entrance` enter, `fast-02` / `productive-exit` leave).
- * Spec also lists `animate-popup-scale-in` / `animate-popup-scale-out` (semantic keyframes).
+ * Tooltip popup motion — timing from `animate.js` (`popup-scale-in` / `popup-scale-out`).
+ * Uses CSS transitions (scale 0.95 → 1, opacity 0 → 1) so Vue `<Transition>` can drive enter/leave.
+ * Matches semantic `animate-popup-scale-*` keyframes (150ms · productive-entrance / 110ms · productive-exit).
  */
 
+export const tooltipMotion = {
+  open: { duration: duration['moderate-01'], curve: curve['productive-entrance'] },
+  close: { duration: duration['fast-02'], curve: curve['productive-exit'] }
+}
+
+/** Close duration — defer unmount until exit animation finishes. */
+export const TOOLTIP_EXIT_MS = Number.parseInt(tooltipMotion.close.duration, 10)
+
 export const popupScaleTransitionEnterActiveClasses = [
   'transition-[transform,opacity]',
   'duration-moderate-01',
diff --git a/packages/webkit/src/components/overlay/tooltip/tooltip.vue b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
index 74a42745..8d13a83e 100644
--- a/packages/webkit/src/components/overlay/tooltip/tooltip.vue
+++ b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
@@ -11,8 +11,6 @@
     popupScaleTransitionLeaveToClasses
   } from './presets/popup-scale-transition.js'
 
-  // Motion utilities (spec): animate-popup-scale-in, animate-popup-scale-out
-
   export type TooltipPlacement = 'top' | 'right' | 'bottom' | 'left'
 
   defineOptions({
@@ -229,6 +227,15 @@
     }
   )
 
+  watch(
+    () => props.text,
+    () => {
+      if (isOpen.value) {
+        nextTick(() => updatePosition())
+      }
+    }
+  )
+
   onMounted(() => {
     globalThis.document?.addEventListener('keydown', onDocumentKeydown)
     globalThis.window?.addEventListener('resize', onScrollOrResize)
@@ -247,7 +254,7 @@
   <span
     ref="triggerRef"
     v-bind="attrs"
-    class="inline-flex focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]"
+    class="inline-flex w-fit shrink-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--bg-canvas)]"
     :data-testid="testId"
     :data-state="isOpen ? 'open' : 'closed'"
     :data-disabled="disabled || null"
@@ -282,7 +289,7 @@
         :data-placement="resolvedPlacement"
         :aria-hidden="!isOpen"
         :style="panelStyle"
-        class="pointer-events-none flex min-h-8 max-w-[var(--container-3xs)] items-center justify-center overflow-clip break-words rounded-[var(--shape-elements)] border border-[var(--border-muted)] bg-[var(--bg-contrast)] p-[var(--spacing-xs)] text-center text-body-sm text-[var(--text-contrast)] [transform-origin:var(--popup-origin,center)] will-change-[transform,opacity]"
+        class="pointer-events-none flex min-h-8 max-w-[var(--container-3xs)] items-center justify-center overflow-clip break-words rounded-[var(--shape-elements)] bg-[var(--bg-contrast)] p-[var(--spacing-xs)] text-center text-body-sm text-[var(--text-contrast)] [transform-origin:var(--popup-origin,center)]"
       >
         {{ text }}
       </div>

From e3c9dc375037c3050a1c0cf84a5b7836778d2308 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Wed, 3 Jun 2026 17:25:18 -0300
Subject: [PATCH 4/4] docs(tooltip): add LongContent story and use body-xs
 typography

Replace the Disabled story with a long-content example on a small transparent info IconButton, and align tooltip panel text with body-xs.
---
 .../stories/webkit/overlay/Tooltip.stories.js | 33 ++++++++++++++++---
 .../components/overlay/tooltip/tooltip.vue    |  2 +-
 2 files changed, 30 insertions(+), 5 deletions(-)

diff --git a/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js b/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
index 511b2d3d..7aff220f 100644
--- a/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
+++ b/apps/storybook/src/stories/webkit/overlay/Tooltip.stories.js
@@ -179,12 +179,37 @@ export const Placements = {
 }
 
 /** @type {import('@storybook/vue3').StoryObj<typeof Tooltip>} */
-export const Disabled = {
-  render: Template,
+export const LongContent = {
+  render: (args) => ({
+    components: { Tooltip, IconButton },
+    setup() {
+      return { args }
+    },
+    template: `
+      <Tooltip
+        v-bind="args"
+        @update:open="args.onUpdateOpen"
+        @show="args.onShow"
+        @hide="args.onHide"
+      >
+        <IconButton
+          icon="pi pi-info-circle"
+          aria-label="More information"
+          kind="transparent"
+          size="small"
+        />
+      </Tooltip>
+    `
+  }),
   args: {
-    disabled: true
+    text: 'This tooltip contains a longer message that wraps across multiple lines when it exceeds the maximum width of the panel.'
   },
   parameters: {
-    docs: { description: { story: 'Tooltip activation is disabled; hover and focus have no effect.' } }
+    docs: {
+      description: {
+        story:
+          'Long text wraps within the tooltip max width (`var(--container-3xs)`). Hover or focus the info icon to preview multi-line layout.'
+      }
+    }
   }
 }
diff --git a/packages/webkit/src/components/overlay/tooltip/tooltip.vue b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
index 8d13a83e..4ee7c54d 100644
--- a/packages/webkit/src/components/overlay/tooltip/tooltip.vue
+++ b/packages/webkit/src/components/overlay/tooltip/tooltip.vue
@@ -289,7 +289,7 @@
         :data-placement="resolvedPlacement"
         :aria-hidden="!isOpen"
         :style="panelStyle"
-        class="pointer-events-none flex min-h-8 max-w-[var(--container-3xs)] items-center justify-center overflow-clip break-words rounded-[var(--shape-elements)] bg-[var(--bg-contrast)] p-[var(--spacing-xs)] text-center text-body-sm text-[var(--text-contrast)] [transform-origin:var(--popup-origin,center)]"
+        class="pointer-events-none flex min-h-8 max-w-[var(--container-3xs)] items-center justify-center overflow-clip break-words rounded-[var(--shape-elements)] bg-[var(--bg-contrast)] p-[var(--spacing-xs)] text-center text-body-xs text-[var(--text-contrast)] [transform-origin:var(--popup-origin,center)]"
       >
         {{ text }}
       </div>