create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/app/ui-kit/src/ui/toggle-button/toggle-button-group.test.tsx

@@ -0,0 +1,97 @@
+// ToggleButtonGroup tests — role=group + single/multiple value semantics +
+// disabled group/con-nút + passthrough cho ToggleButton không `value`.
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ToggleButton } from './index.js';
+import { ToggleButtonGroup } from './toggle-button-group.js';
+
+afterEach(cleanup);
+
+const VIEWS = (
+  <>
+    <ToggleButton value="list">List</ToggleButton>
+    <ToggleButton value="board">Board</ToggleButton>
+    <ToggleButton value="timeline">Timeline</ToggleButton>
+  </>
+);
+
+describe('ToggleButtonGroup', () => {
+  it('role=group + aria-label', () => {
+    render(<ToggleButtonGroup ariaLabel="View mode">{VIEWS}</ToggleButtonGroup>);
+    expect(screen.getByRole('group', { name: 'View mode' })).toBeInTheDocument();
+  });
+
+  it('single: value="list" → nút List pressed; click khác → onChange(value mới)', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <ToggleButtonGroup value="list" onChange={onChange} ariaLabel="View">
+        {VIEWS}
+      </ToggleButtonGroup>,
+    );
+    expect(screen.getByRole('button', { name: 'List' })).toHaveAttribute('aria-pressed', 'true');
+    expect(screen.getByRole('button', { name: 'Board' })).toHaveAttribute('aria-pressed', 'false');
+    await user.click(screen.getByRole('button', { name: 'Board' }));
+    expect(onChange).toHaveBeenCalledWith('board');
+  });
+
+  it('multiple: click thêm vào mảng; bấm nút đang chọn → bỏ khỏi mảng', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <ToggleButtonGroup multiple value={['bugs']} onChange={onChange} ariaLabel="Filters">
+        <ToggleButton value="bugs">Bugs</ToggleButton>
+        <ToggleButton value="features">Features</ToggleButton>
+      </ToggleButtonGroup>,
+    );
+    await user.click(screen.getByRole('button', { name: 'Features' }));
+    expect(onChange).toHaveBeenCalledWith(['bugs', 'features']);
+    await user.click(screen.getByRole('button', { name: 'Bugs' }));
+    expect(onChange).toHaveBeenCalledWith([]);
+  });
+
+  it('group disabled → mọi nút disabled, không gọi onChange', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <ToggleButtonGroup disabled value="list" onChange={onChange} ariaLabel="View">
+        {VIEWS}
+      </ToggleButtonGroup>,
+    );
+    for (const name of ['List', 'Board', 'Timeline']) {
+      expect(screen.getByRole('button', { name })).toBeDisabled();
+    }
+    await user.click(screen.getByRole('button', { name: 'Board' }));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('disabled từng nút vẫn ăn khi group không khoá', () => {
+    render(
+      <ToggleButtonGroup ariaLabel="View">
+        <ToggleButton value="a">A</ToggleButton>
+        <ToggleButton value="b" disabled>B</ToggleButton>
+      </ToggleButtonGroup>,
+    );
+    expect(screen.getByRole('button', { name: 'B' })).toBeDisabled();
+    expect(screen.getByRole('button', { name: 'A' })).not.toBeDisabled();
+  });
+
+  it('ToggleButton không `value` → giữ nguyên checked/onChange riêng (đứng lẻ trong group)', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(
+      <ToggleButtonGroup value="x" onChange={() => {}} ariaLabel="Mixed">
+        <ToggleButton checked onChange={onChange}>Loose</ToggleButton>
+      </ToggleButtonGroup>,
+    );
+    expect(screen.getByRole('button', { name: 'Loose' })).toHaveAttribute('aria-pressed', 'true');
+    await user.click(screen.getByRole('button', { name: 'Loose' }));
+    expect(onChange).toHaveBeenCalledWith(false); // onChange gốc, không phải onChange group
+  });
+
+  it('className passthrough ra container group', () => {
+    render(<ToggleButtonGroup className="marker-group" ariaLabel="View">{VIEWS}</ToggleButtonGroup>);
+    expect(screen.getByRole('group', { name: 'View' })).toHaveClass('marker-group');
+  });
+});

package/stack-template/app/ui-kit/src/ui/toggle-button/toggle-button-group.tsx

@@ -0,0 +1,81 @@
+// ToggleButtonGroup — cluster các ToggleButton thành group chọn 1 (mặc định)
+// hoặc nhiều (multiple). Group quản checked qua props `value` của từng nút:
+// cloneElement tiêm checked/onChange, nút đứng lẻ (không `value`) giữ nguyên.
+// A11y: role=group + aria-label; từng nút vẫn dùng aria-pressed của ToggleButton.
+import { Children, Fragment, cloneElement, isValidElement, type ReactElement, type ReactNode } from 'react';
+import { type ToggleButtonProps } from './index.js';
+
+interface BaseGroupProps {
+  /** Khoá toàn group (nút lẻ vẫn có thể tự disabled). */
+  disabled?: boolean;
+  /** Nhãn a11y của group (role=group). */
+  ariaLabel?: string;
+  className?: string;
+  /** Các `ToggleButton` con — mỗi nút cần `value` để group quản trạng thái. */
+  children: ReactNode;
+}
+
+interface SingleGroupProps extends BaseGroupProps {
+  /** Bỏ `multiple` → chọn 1: value là 1 chuỗi. */
+  multiple?: false;
+  value?: string;
+  onChange?: (value: string) => void;
+}
+
+interface MultiGroupProps extends BaseGroupProps {
+  /** Chọn nhiều: value là mảng; bấm nút đang chọn → bỏ khỏi mảng. */
+  multiple: true;
+  value?: string[];
+  onChange?: (value: string[]) => void;
+}
+
+export type ToggleButtonGroupProps = SingleGroupProps | MultiGroupProps;
+
+export function ToggleButtonGroup(props: ToggleButtonGroupProps) {
+  const { disabled, ariaLabel, className, children } = props;
+  const multiple = props.multiple === true;
+  const value: string | string[] | undefined = props.value;
+  const onChange = props.onChange as ((v: string | string[]) => void) | undefined;
+
+  const pick = (v: string) => {
+    if (!onChange) return;
+    if (multiple) {
+      const arr = Array.isArray(value) ? value : [];
+      onChange(arr.includes(v) ? arr.filter((x) => x !== v) : [...arr, v]);
+    } else {
+      onChange(v);
+    }
+  };
+
+  // Children.map KHÔNG xẻ fragment — child đầu có thể là chính Fragment
+  // (children viết `<Group><>{...}</></Group>`), phải đi vào trong mới thấy
+  // các ToggleButton. Đệ quy xử lý fragment, clone từng nút có `value`.
+  const injectInto = (node: ReactNode): ReactNode => {
+    if (!isValidElement(node)) return node;
+    if (node.type === Fragment) {
+      return <Fragment>{Children.map((node.props as { children?: ReactNode }).children, injectInto)}</Fragment>;
+    }
+    const btn = node as ReactElement<ToggleButtonProps>;
+    const v = btn.props.value;
+    // Nút không `value` (đứng lẻ trong group) — giữ nguyên checked/onChange riêng
+    if (v === undefined) return node;
+    const checked = multiple ? Array.isArray(value) && value.includes(v) : value === v;
+    return cloneElement(btn, {
+      checked,
+      disabled: disabled || btn.props.disabled,
+      onChange: () => pick(v),
+    });
+  };
+
+  const items = Children.map(children, injectInto);
+
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className={`inline-flex items-center gap-2${className ? ` ${className}` : ''}`}
+    >
+      {items}
+    </div>
+  );
+}

package/stack-template/app/ui-kit/src/ui/toggle-button/toggle-button.stories.tsx

@@ -0,0 +1,46 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ToggleButton } from './index';
+
+/** Button with a pressed state — `checked` surfaces as `aria-pressed`. */
+const meta = { title: 'Forms/ToggleButton', component: ToggleButton, tags: ['autodocs'] } satisfies Meta<typeof ToggleButton>;
+export default meta;
+type S = StoryObj<typeof meta>;
+
+/** Basic — unchecked state. */
+export const Basic: S = { args: { children: 'Toggle', checked: false, onChange: () => {} } };
+
+/** Checked — pressed state. */
+export const Checked: S = { args: { children: 'On', checked: true } };
+
+/** Disabled — locked, dimmed (real prop: disabled). */
+export const Disabled: S = {
+  args: { children: 'Locked', checked: true, disabled: true, onChange: () => {} },
+};
+
+/** Controlled — useState demo: click flips checked. */
+export const Controlled: S = {
+  args: { children: 'Toggle' },
+  render: () => <ToggleButtonControlledDemo />,
+};
+
+/** DarkTheme — both states on dark canvas. */
+export const DarkTheme: S = {
+  args: { children: 'Toggle' },
+  render: () => (
+    <div data-bp-theme="dark" className="flex w-[280px] gap-3 rounded-xl bg-canvas p-4">
+      <ToggleButton checked={false} onChange={() => {}}>Off</ToggleButton>
+      <ToggleButton checked={true} onChange={() => {}}>On</ToggleButton>
+    </div>
+  ),
+};
+
+function ToggleButtonControlledDemo() {
+  const [on, setOn] = useState(false);
+  return (
+    <div className="grid max-w-[240px] gap-3">
+      <ToggleButton checked={on} onChange={setOn}>Enable notifications</ToggleButton>
+      <p className="m-0 font-mono text-meta text-ink3">checked: <strong className="text-ink">{String(on)}</strong></p>
+    </div>
+  );
+}

package/stack-template/app/ui-kit/src/ui/toggle-button/toggle-button.test.tsx

@@ -0,0 +1,38 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ToggleButton } from './index.js';
+afterEach(cleanup);
+describe('ToggleButton', () => {
+  it('aria-pressed + click → onChange(!checked)', async () => {
+    const onChange = vi.fn();
+    render(<ToggleButton checked={false} onChange={onChange}>Toggle</ToggleButton>);
+    expect(screen.getByRole('button', { name: 'Toggle' })).toHaveAttribute('aria-pressed', 'false');
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Toggle' }));
+    expect(onChange).toHaveBeenCalledWith(true);
+  });
+});
+
+describe('ToggleButton — matrix (props thật: checked/onChange/disabled/className)', () => {
+  it('checked=true → click → onChange(false) (flip ngược)', async () => {
+    const onChange = vi.fn();
+    render(<ToggleButton checked onChange={onChange}>Bật</ToggleButton>);
+    expect(screen.getByRole('button', { name: 'Bật' })).toHaveAttribute('aria-pressed', 'true');
+    await userEvent.setup().click(screen.getByRole('button', { name: 'Bật' }));
+    expect(onChange).toHaveBeenCalledWith(false);
+  });
+
+  it('disabled → không bấm được, không gọi onChange', async () => {
+    const onChange = vi.fn();
+    render(<ToggleButton disabled onChange={onChange}>Khoá</ToggleButton>);
+    const btn = screen.getByRole('button', { name: 'Khoá' });
+    expect(btn).toBeDisabled();
+    await userEvent.setup().click(btn);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('className passthrough', () => {
+    render(<ToggleButton className="marker">c</ToggleButton>);
+    expect(screen.getByRole('button', { name: 'c' })).toHaveClass('marker');
+  });
+});

package/stack-template/app/ui-kit/src/ui/toolbar/index.tsx

@@ -0,0 +1,18 @@
+// Toolbar — flex container start/end (antd Toolbar lite).
+import type { ReactNode } from 'react';
+
+export interface ToolbarProps {
+  children: ReactNode;
+  /** Node bên phải. */
+  extra?: ReactNode;
+  className?: string;
+}
+
+export function Toolbar({ children, extra, className }: ToolbarProps) {
+  return (
+    <div className={`flex flex-wrap items-center justify-between gap-2${className ? ` ${className}` : ''}`}>
+      <div className="flex items-center gap-2">{children}</div>
+      {extra && <div className="flex items-center gap-2">{extra}</div>}
+    </div>
+  );
+}

package/stack-template/app/ui-kit/src/ui/toolbar/toolbar.stories.tsx

@@ -0,0 +1,35 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button/index';
+import { Icon } from '../icons/index';
+import { Toolbar } from './index';
+/** Toolbar row — left tools, right actions (extra slot). */
+const meta = { title: 'Navigation/Toolbar', component: Toolbar, tags: ['autodocs'] } satisfies Meta<typeof Toolbar>;
+export default meta;
+type S = StoryObj<typeof meta>;
+export const MacDinh: S = {
+  name: 'Default',
+  args: { children: <span>Công cụ</span>, extra: <span>Extra</span> },
+};
+
+export const WithExtra: S = {
+  name: 'With extra — left tools + right actions (filter bar)',
+  args: {
+    children: (
+      <>
+        <span className="flex items-center gap-1.5 text-body text-ink2">
+          <Icon name="filter" size={14} />
+          Filter tools
+        </span>
+        <Button size="small">Clear</Button>
+      </>
+    ),
+    extra: (
+      <>
+        <Button size="small">Reset</Button>
+        <Button size="small" type="primary">
+          Apply
+        </Button>
+      </>
+    ),
+  },
+};

package/stack-template/app/ui-kit/src/ui/toolbar/toolbar.test.tsx

@@ -0,0 +1,11 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Toolbar } from './index.js';
+afterEach(cleanup);
+describe('Toolbar', () => {
+  it('children + extra render', () => {
+    render(<Toolbar extra={<span>extra</span>}>main</Toolbar>);
+    expect(screen.getByText('main')).toBeInTheDocument();
+    expect(screen.getByText('extra')).toBeInTheDocument();
+  });
+});

package/stack-template/app/ui-kit/src/ui/tooltip/index.tsx

@@ -0,0 +1,61 @@
+// Tooltip — bubble hint khi hover/focus (antd look: nền spotlight --tooltip-bg,
+// trắng 14px, radius 8, padding 6px 8px, max-width 250, mũi tên 8px vuông xoay 45°.
+// Placement 'top' (default). Portal-free: absolute trong wrapper relative.
+// A11y: bubble id + trigger aria-describedby (cloneElement), ESC đóng khi đang mở.
+import { cloneElement, isValidElement, useId, useState, type KeyboardEvent, type ReactElement, type ReactNode } from 'react';
+
+export interface TooltipProps {
+  /** Nội dung bubble. */
+  title: ReactNode;
+  /** Trigger — bubble bọc quanh element này (hover/focus mở). */
+  children: ReactNode;
+  /** Vị trí bubble so với trigger. */
+  placement?: 'top' | 'bottom';
+  className?: string;
+}
+
+export function Tooltip({ title, children, placement = 'top', className }: TooltipProps) {
+  const [open, setOpen] = useState(false);
+  const bubbleId = useId();
+
+  const onKeyDown = (e: KeyboardEvent<HTMLSpanElement>) => {
+    if (e.key === 'Escape') setOpen(false);
+  };
+
+  // Wire aria-describedby thẳng lên trigger element (SR đọc bubble khi focus trigger)
+  const trigger = isValidElement(children)
+    ? cloneElement(children as ReactElement<Record<string, unknown>>, {
+        'aria-describedby': open ? bubbleId : undefined,
+      })
+    : children;
+
+  return (
+    <span
+      className={`relative inline-flex${className ? ` ${className}` : ''}`}
+      onMouseEnter={() => setOpen(true)}
+      onMouseLeave={() => setOpen(false)}
+      onFocus={() => setOpen(true)}
+      onBlur={() => setOpen(false)}
+      onKeyDown={onKeyDown}
+    >
+      {trigger}
+      {open && (
+        <span
+          role="tooltip"
+          id={bubbleId}
+          className={`pointer-events-none absolute left-1/2 z-[var(--z-tooltip)] w-max max-w-[250px] -translate-x-1/2 rounded-lg bg-[var(--tooltip-bg)] px-2 py-1.5 text-body text-white animate-[bp-fade-in_var(--motion-fast)_var(--ease-enter)] ${
+            placement === 'top' ? 'bottom-[calc(100%+8px)]' : 'top-[calc(100%+8px)]'
+          }`}
+        >
+          {title}
+          <span
+            aria-hidden="true"
+            className={`absolute left-1/2 size-2 -translate-x-1/2 rotate-45 bg-[var(--tooltip-bg)] ${
+              placement === 'top' ? 'top-[calc(100%-4px)]' : 'bottom-[calc(100%-4px)]'
+            }`}
+          />
+        </span>
+      )}
+    </span>
+  );
+}

package/stack-template/app/ui-kit/src/ui/tooltip/tooltip.stories.tsx

@@ -0,0 +1,81 @@
+// Parity matrix antd→tokens: docs/parity-matrix.md
+// Tooltip stories — placement top/bottom (component supports 2 directions, not 4),
+// trigger hover + focus.
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Button } from '../button/index';
+import { Tooltip } from './index';
+
+/** Hover/focus hint bubble — portal-free, wraps the trigger in place. */
+const meta = { title: 'Feedback/Tooltip', tags: ['autodocs'] } satisfies Meta;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Top: Story = {
+  name: 'Placement top (default) — try hovering',
+  render: () => (
+    <Tooltip title="This tooltip appears above">
+      <Button>Hover me</Button>
+    </Tooltip>
+  ),
+};
+
+export const Bottom: Story = {
+  name: 'Placement bottom',
+  render: () => (
+    <Tooltip title="This tooltip appears below" placement="bottom">
+      <Button>Hover me</Button>
+    </Tooltip>
+  ),
+};
+
+export const Trigger: Story = {
+  name: 'Trigger — hover + focus (keyboard Tab)',
+  render: () => (
+    <div className="flex gap-4">
+      <Tooltip title="Focusable button — Tab here shows the bubble">
+        <Button>Focus/hover</Button>
+      </Tooltip>
+      <Tooltip title="Links receive focus too" placement="bottom">
+        <a href="#" className="text-accent no-underline">
+          Demo link
+        </a>
+      </Tooltip>
+    </div>
+  ),
+};
+
+export const LongContent: Story = {
+  name: 'Long content — max-width 250px wrap',
+  render: () => (
+    <Tooltip title="Long hint text to show wrapping: this task syncs through the gateway, retries 3 times, then parks the event in the DLQ for inspection.">
+      <Button>Hover for long hint</Button>
+    </Tooltip>
+  ),
+};
+
+export const DarkTheme: Story = {
+  name: 'DarkTheme — black bubble same in both themes (antd)',
+  render: () => (
+    <div data-bp-theme="dark" className="p-4">
+      <Tooltip title="Dark scope tooltip">
+        <Button>Hover me (dark)</Button>
+      </Tooltip>
+    </div>
+  ),
+};
+
+export const RichContent: Story = {
+  name: 'Rich content — ReactNode title (strong + accent)',
+  render: () => (
+    <Tooltip
+      title={
+        <span>
+          <strong className="text-white">Deadline</strong> — syncs through the gateway, retries 3×, then parks in{' '}
+          <span className="text-accent">DLQ</span>
+        </span>
+      }
+    >
+      <Button>Hover for rich hint</Button>
+    </Tooltip>
+  ),
+};

package/stack-template/app/ui-kit/src/ui/tooltip/tooltip.test.tsx

@@ -0,0 +1,120 @@
+// Tooltip tests — hover/focus hiện bubble, leave ẩn, placement class.
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+import { Tooltip } from './index.js';
+
+afterEach(cleanup);
+
+describe('Tooltip', () => {
+  it('mặc định ẩn; hover hiện bubble + arrow; leave ẩn', () => {
+    render(
+      <Tooltip title="Gợi ý">
+        <button>Trigger</button>
+      </Tooltip>,
+    );
+    expect(screen.queryByRole('tooltip')).toBeNull();
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Trigger' }));
+    expect(screen.getByRole('tooltip')).toHaveTextContent('Gợi ý');
+    fireEvent.mouseLeave(screen.getByRole('button', { name: 'Trigger' }));
+    expect(screen.queryByRole('tooltip')).toBeNull();
+  });
+
+  it('focus hiện bubble (a11y bàn phím)', () => {
+    render(
+      <Tooltip title="Gợi ý focus">
+        <button>Trigger</button>
+      </Tooltip>,
+    );
+    fireEvent.focus(screen.getByRole('button', { name: 'Trigger' }));
+    expect(screen.getByRole('tooltip')).toBeInTheDocument();
+  });
+
+  it('placement bottom → class vị trí đáy', () => {
+    render(
+      <Tooltip title="x" placement="bottom">
+        <button>Trigger</button>
+      </Tooltip>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'Trigger' }));
+    expect(screen.getByRole('tooltip').className).toContain('top-[calc(100%+8px)]');
+  });
+});
+
+describe('Tooltip — branch phụ', () => {
+  it('placement top (mặc định) → bubble đáy trigger', () => {
+    render(
+      <Tooltip title="top">
+        <button>T</button>
+      </Tooltip>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'T' }));
+    expect(screen.getByRole('tooltip').className).toContain('bottom-[calc(100%+8px)]');
+  });
+});
+
+describe('Tooltip — branch phụ (Tier 5 sweep)', () => {
+  it('arrow vị trí theo placement bottom', () => {
+    render(
+      <Tooltip title="x" placement="bottom">
+        <button>T</button>
+      </Tooltip>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'T' }));
+    expect(screen.getByRole('tooltip').querySelector('span[aria-hidden]')?.className).toContain('bottom-[calc(100%-4px)]');
+  });
+});
+
+describe('Tooltip — ESC (a11y batch ⑫ worker C)', () => {
+  it('ESC đóng bubble khi đang mở qua focus', () => {
+    render(
+      <Tooltip title="gợi ý">
+        <button>T</button>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole('button', { name: 'T' });
+    fireEvent.focus(trigger);
+    expect(screen.getByRole('tooltip')).toBeInTheDocument();
+    fireEvent.keyDown(trigger, { key: 'Escape' });
+    expect(screen.queryByRole('tooltip')).toBeNull();
+  });
+});
+
+describe('Tooltip — describedby wiring (worker H)', () => {
+  it('open → bubble có id, trigger nhận aria-describedby trỏ đúng; đóng → bỏ attr', () => {
+    render(
+      <Tooltip title="hint">
+        <button>T</button>
+      </Tooltip>,
+    );
+    const trigger = screen.getByRole('button', { name: 'T' });
+    expect(trigger).not.toHaveAttribute('aria-describedby');
+    fireEvent.focus(trigger);
+    const bubble = screen.getByRole('tooltip');
+    expect(bubble).toHaveAttribute('id');
+    expect(trigger).toHaveAttribute('aria-describedby', bubble.id);
+    fireEvent.blur(trigger);
+    expect(trigger).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('children không phải element (text node) → vẫn render, không cloneElement lỗi', () => {
+    render(<Tooltip title="hint">plain text</Tooltip>);
+    const wrapper = screen.getByText('plain text'); // text nằm trực tiếp trong wrapper span
+    fireEvent.mouseEnter(wrapper);
+    expect(screen.getByRole('tooltip')).toHaveTextContent('hint');
+  });
+});
+
+describe('Tooltip — token surface (dark-safety, lead decision 2026-10-18)', () => {
+  it('bubble + arrow dùng token --tooltip-bg (không hardcode bg-black/85)', () => {
+    render(
+      <Tooltip title="hint">
+        <button>T</button>
+      </Tooltip>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', { name: 'T' }));
+    const bubble = screen.getByRole('tooltip');
+    expect(bubble.className).toContain('bg-[var(--tooltip-bg)]');
+    expect(bubble.className).not.toContain('bg-black/85');
+    expect((bubble.querySelector('span[aria-hidden]') as HTMLElement).className).toContain('bg-[var(--tooltip-bg)]');
+  });
+});