# Tooltip — Figma alignment fix spec (X.4.2 batch)

## Inputs (✓ all read)

- ✓ `figma-data/normalized/figma-mcp-cache/tooltip.tsx` (axes: darkTheme(boolean) × pointing(left up / left down / Center up / Center down / right up / right down))
- ✓ `src/canonical/Tooltip.vue` (wrapper, maps `pointing` → 12-value `placement`)
- ✓ `src/components/Tooltip/Tooltip.vue` (impl)
- ✓ `figma-data/normalized/figma-styles.json` (L3 shadow exists)
- ✓ `src/design-system/translation/token-aliases.ts`
- ✓ `src/design-system/translation/prop-aliases.md` (Tooltip darkTheme axis alias documented)
- ✓ `src/design-system/translation/icon-aliases.ts`
- ✓ `src/tokens/variables.css`

## Mismatches by dimension

### Spacing

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.tooltip-box` padding | `4px 8px` raw | `px-[8px] py-[4px]` (figma raw — no spacing token referenced in cache) | replace with `var(--sp-xxs) var(--sp-xs)` (4=xxs, 8=xs) |
| `.tooltip-box-*` offset (top/bottom/left/right) | `calc(100% + 6px)` raw | implicit (mb-[-6px] / top-[4.49px / 0.53px]) — design uses 6px arrow offset | propose domain token `--tooltip-arrow-offset: 6px` (no canonical 6px spacing token; closest `--sp-xs` is 8) |
| `.tooltip-arrow` left/right pseudo offsets (`12px`, `10px`) | raw | figma: `left-[11.76px]` ≈ 12, arrow content positions within 8.485 box | replace `12px` with `var(--sp-s)` (12 = `--sp-s`); `10px` arrow vert offset domain token |
| `.tooltip-anchor` padding (test-only stub) | `width: 24px; height: 8px` | n/a (canonical-only) | leave as test stub OR mark non-figma helper |
| `.tooltip-arrow` size `8.5px` | raw | `size-[8.485px]` figma raw | non-token literal (45° rotated 6px square produces 8.485 hypotenuse); keep raw or domain token `--tooltip-arrow-hyp` |

### Color

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.tooltip-box--dark` `--tooltip-bg` | `var(--bg-layer4)` | `bg-[var(--ux\/grey\/grey-10-\#353535,#353535)]` → `--color-grey-10` (or `--bg-layer4` since dark `--bg-layer4 = #353535`) | **MISMATCH**: figma binds to `grey-10` (theme-stable). Canonical uses `--bg-layer4` (theme-aware: dark=#353535, light=#dbdbdb). For Tooltip dark variant the bg should be **theme-stable #353535** regardless of site theme. **Fix**: replace with `var(--color-grey-10)` |
| `.tooltip-box--dark` `--tooltip-border` | `var(--line-border)` (theme-aware) | `border-[var(--ux\/grey\/grey-8-\#595959,#595959)]` → `--color-grey-8` | **MISMATCH**: figma uses theme-stable grey-8. **Fix**: `var(--color-grey-8)` for dark variant. |
| `.tooltip-box--dark` `--tooltip-text` | `var(--text-body)` (theme-aware) | `text-[color:var(--ux\/grey\/grey-2-\#f8f8f8,#f8f8f8)]` → `--color-grey-2` | **MISMATCH**: figma theme-stable grey-2. **Fix**: `var(--color-grey-2)` for dark variant. |
| `.tooltip-box--light` `--tooltip-bg` | `var(--bg-layer1)` (theme-aware) | `bg-[var(--ux\/grey\/grey-1-\#ffffff,white)]` → `--color-white` | **MISMATCH**: figma theme-stable white. **Fix**: `var(--color-white)`. |
| `.tooltip-box--light` `--tooltip-border` | `var(--line-border)` (theme-aware) | `border-[var(--ux\/grey\/grey-3-\#f0f0f0,#f0f0f0)]` → `--color-grey-3` | **MISMATCH**: theme-stable. **Fix**: `var(--color-grey-3)`. |
| `.tooltip-box--light` `--tooltip-text` | `var(--text-body)` (theme-aware) | `text-[color:var(--ux\/grey\/grey-13-\#141414,#141414)]` → `--color-grey-13` | **MISMATCH**: theme-stable. **Fix**: `var(--color-grey-13)`. |

**Root cause**: Tooltip has its own `theme: 'dark' \| 'light'` axis (from figma `darkTheme`), so it must use **theme-stable** color tokens — not site-theme-aware ones. Same pattern as Notification's `--notification-bg-dark/light` tokens already in `variables.css`. **Action**: define domain tokens.

### Typography

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.tooltip-box` `font-size` 12 + `line-height` 16 + `font-weight` 400 (no family) | 3 raw lines | `Roboto/12 tips` → `--text-style-tips` | replace with `font: var(--text-style-tips);` |

### Effect

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.tooltip-box` `box-shadow` (3-layer hardcoded) | `0 12px 48px 16px rgb(0 0 0 / 3%), 0 9px 28px 0 rgb(0 0 0 / 5%), 0 6px 16px -8px rgb(0 0 0 / 8%)` | `L3 shadow` (per figma cache: offsets 12/9/6, radii 48/28/16, spread 16/0/-8, opacities 03/0D/14 = 1.2%/5.1%/7.8%) → `--shadow-l3` | **MISMATCH** opacities (canonical 3/5/8% vs figma 1.2/5.1/7.8%). **Fix**: replace 3-line literal with `box-shadow: var(--shadow-l3);` (token already aligned to figma 真源 per commit 2026-05-07) |
| (drop-shadow on figma outer wrapper) | n/a | `drop-shadow-[0px_6px_8px..., 0px_9px_14px..., 0px_12px_24px...]` (different stack from L3 — looks like alt offset) | review: figma cache outer drop-shadow doesn't match L3 — likely figma rendering its own drop-shadow filter for arrow visibility. Canonical only sets one shadow on `.tooltip-box` — assume L3 is authoritative (cache description says "L3 shadow"). |

### Composition

- Canonical uses single `<div class="tooltip-box">` + `<span class="tooltip-arrow">`. Figma uses inner Content frame + separate arrow wrapper with rotated inner div. Visual parity OK; markup divergence approved.
- Canonical `tooltip-anchor` (visible stub when no slot trigger) is canonical-only — not in figma. Acceptable test/dev affordance.

### Variant coverage

| Axis | Figma values | Canonical | Status |
|---|---|---|---|
| darkTheme (figma boolean) → theme axis | `true` / `false` | canonical wrapper: `'on' \| 'off'`; impl: `'dark' \| 'light'` | per `prop-aliases.md` GLOBAL axis alias (table A/B): figma `darkTheme=on→dark`, `off→light`. ✓ aligned via wrapper. |
| pointing | `left up`, `left down`, `Center up`, `Center down`, `right up`, `right down` | wrapper `Pointing` enum 6 values, mapped to placement: `bottom-start, top-start, bottom, top, bottom-end, top-end` | ✓ all 6 values covered (commit 616e719 confirmed) |

Per Phase X.4.2 note: pointing axis 6 values **fully covered** in canonical wrapper. ✓

## Token usage summary

After fix the impl file should reference only:

- Spacing: `--sp-xxs`, `--sp-xs`, `--sp-s` (and proposed `--tooltip-arrow-offset`)
- Color (theme-stable for tooltip dark/light variants): `--color-grey-2`, `--color-grey-3`, `--color-grey-8`, `--color-grey-10`, `--color-grey-13`, `--color-white`
- Typography: `--text-style-tips`
- Effect: `--shadow-l3`
- Domain (proposed): `--tooltip-bg-dark`, `--tooltip-bg-light`, `--tooltip-border-dark`, `--tooltip-border-light`, `--tooltip-text-dark`, `--tooltip-text-light`, `--tooltip-arrow-offset`

## Refactor scope

1. `src/components/Tooltip/Tooltip.vue` `<style scoped>`:
   - Replace `padding: 4px 8px` with `padding: var(--sp-xxs) var(--sp-xs)`.
   - Replace `font-size: 12px; font-weight: 400; line-height: 16px` with `font: var(--text-style-tips);`.
   - Replace 3-line `box-shadow` literal with `box-shadow: var(--shadow-l3);`.
   - Update `.tooltip-box--dark` and `.tooltip-box--light` blocks to use proposed domain tokens (theme-stable values).
   - Replace placement offset `calc(100% + 6px)` with `calc(100% + var(--tooltip-arrow-offset))`.
   - Replace start/end offsets `12px` (4 occurrences) with `var(--sp-s)`.
   - Replace start/end vertical offsets `10px` (4 occurrences) — propose alias to `--tooltip-arrow-offset` or domain `--tooltip-vert-offset` (10 has no canonical match).
2. `src/tokens/variables.css` — add domain tokens after Notification block:
   ```
   /* Tooltip — has own theme axis, theme-stable per variant */
   --tooltip-bg-dark: var(--color-grey-10);
   --tooltip-bg-light: var(--color-white);
   --tooltip-border-dark: var(--color-grey-8);
   --tooltip-border-light: var(--color-grey-3);
   --tooltip-text-dark: var(--color-grey-2);
   --tooltip-text-light: var(--color-grey-13);
   --tooltip-arrow-offset: 6px;       /* gap between trigger and box */
   --tooltip-vert-offset: 10px;       /* {left,right}-{start,end} vertical inset */
   ```
3. `src/design-system/translation/prop-aliases.md`:
   - Tooltip already in "Boolean Property Aliases" + GLOBAL axis alias tables. ✓
   - Confirm `pointing` axis values registered (currently implicit in canonical — `Tooltip` row table C says "仍是 darkTheme: 'on' \| 'off'"; pointing axis not yet logged). Add a new entry for pointing axis if Phase X.4.2 demands.

## Blockers / open decisions

- Canonical impl `theme: 'dark'/'light'` is wrapper-derived; figma boolean `darkTheme=true` → canonical wrapper `'on'` → impl `'dark'`. Currently consistent. No change.
- Default theme: canonical wrapper defaults `darkTheme: 'off'` (light); figma default `darkTheme: true` (dark). **Open**: align defaults to figma? Recommend yes (`darkTheme: 'on'`).
- 10px start/end offset (left-start/right-start) has no canonical token — domain `--tooltip-vert-offset` is the cleanest fix; alternative is to round to `var(--sp-s)` (12) but that changes visuals.
- Figma cache outer wrapper `drop-shadow` differs from L3 spec — using L3 (per cache description text "L3 shadow") as truth.