diff --git a/react/jest.config.js b/react/jest.config.js
new file mode 100644
index 0000000..75a5a79
--- /dev/null
+++ b/react/jest.config.js
@@ -0,0 +1,12 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  testMatch: ['**/*.test.ts', '**/*.test.tsx'],
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      { tsconfig: { jsx: 'react-jsx', module: 'commonjs', esModuleInterop: true } },
+    ],
+  },
+};
diff --git a/react/jest.setup.ts b/react/jest.setup.ts
new file mode 100644
index 0000000..7b0828b
--- /dev/null
+++ b/react/jest.setup.ts
@@ -0,0 +1 @@
+import '@testing-library/jest-dom';
diff --git a/react/package.json b/react/package.json
index eb6c0c7..f89666a 100644
--- a/react/package.json
+++ b/react/package.json
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --watch --dts",
-    "lint": "eslint src/**/*.ts"
+    "lint": "eslint src/**/*.ts",
+    "test": "jest"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -21,10 +22,17 @@
     "@bc-forge/sdk": "file:../sdk"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.4.0",
+    "@testing-library/react": "^16.0.0",
+    "@types/jest": "^29.5.0",
     "@types/react": "^18.0.0",
     "@types/react-dom": "^18.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "ts-jest": "^29.1.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"
   }
diff --git a/react/src/components/Alert.tsx b/react/src/components/Alert.tsx
new file mode 100644
index 0000000..9aec061
--- /dev/null
+++ b/react/src/components/Alert.tsx
@@ -0,0 +1,71 @@
+import React, { forwardRef } from 'react';
+
+export type AlertVariant = 'info' | 'success' | 'warning' | 'danger';
+
+export interface AlertProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Visual + semantic style of the alert. @default 'info' */
+  variant?: AlertVariant;
+  /** Optional bold title rendered above the content. */
+  title?: React.ReactNode;
+  /** When provided, renders a dismiss button that calls this handler. */
+  onDismiss?: () => void;
+  /** Accessible label for the dismiss button. @default 'Dismiss alert' */
+  dismissLabel?: string;
+}
+
+const VARIANT_STYLES: Record<AlertVariant, React.CSSProperties> = {
+  info: { backgroundColor: '#eff6ff', borderColor: '#bfdbfe', color: '#1e40af' },
+  success: { backgroundColor: '#f0fdf4', borderColor: '#bbf7d0', color: '#166534' },
+  warning: { backgroundColor: '#fffbeb', borderColor: '#fde68a', color: '#92400e' },
+  danger: { backgroundColor: '#fef2f2', borderColor: '#fecaca', color: '#991b1b' },
+};
+
+/** Alert banner; role is "alert" for danger/warning and "status" otherwise. */
+export const Alert = forwardRef<HTMLDivElement, AlertProps>(function Alert(
+  { variant = 'info', title, onDismiss, dismissLabel = 'Dismiss alert', style, children, ...rest },
+  ref,
+) {
+  const defaultRole = variant === 'danger' || variant === 'warning' ? 'alert' : 'status';
+
+  return (
+    <div
+      ref={ref}
+      role={defaultRole}
+      style={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: 8,
+        padding: '12px 14px',
+        border: '1px solid',
+        borderRadius: 8,
+        ...VARIANT_STYLES[variant],
+        ...style,
+      }}
+      {...rest}
+    >
+      <div style={{ flex: 1, minWidth: 0 }}>
+        {title ? <div style={{ fontWeight: 700, marginBottom: 2 }}>{title}</div> : null}
+        <div style={{ fontSize: 14 }}>{children}</div>
+      </div>
+      {onDismiss ? (
+        <button
+          type="button"
+          onClick={onDismiss}
+          aria-label={dismissLabel}
+          style={{
+            flexShrink: 0,
+            border: 'none',
+            background: 'transparent',
+            cursor: 'pointer',
+            color: 'inherit',
+            fontSize: 18,
+            lineHeight: 1,
+            padding: 2,
+          }}
+        >
+          &times;
+        </button>
+      ) : null}
+    </div>
+  );
+});
diff --git a/react/src/components/Badge.tsx b/react/src/components/Badge.tsx
new file mode 100644
index 0000000..e86ead7
--- /dev/null
+++ b/react/src/components/Badge.tsx
@@ -0,0 +1,64 @@
+import React, { forwardRef } from 'react';
+
+export type BadgeVariant =
+  | 'default'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info';
+
+export type BadgeSize = 'sm' | 'md' | 'lg';
+
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /** Visual style of the badge. @default 'default' */
+  variant?: BadgeVariant;
+  /** Size of the badge. @default 'md' */
+  size?: BadgeSize;
+}
+
+const VARIANT_STYLES: Record<BadgeVariant, React.CSSProperties> = {
+  default: { backgroundColor: '#f3f4f6', color: '#374151' },
+  primary: { backgroundColor: '#e0e7ff', color: '#3730a3' },
+  success: { backgroundColor: '#dcfce7', color: '#166534' },
+  warning: { backgroundColor: '#fef3c7', color: '#92400e' },
+  danger: { backgroundColor: '#fee2e2', color: '#991b1b' },
+  info: { backgroundColor: '#cffafe', color: '#155e75' },
+};
+
+const SIZE_STYLES: Record<BadgeSize, React.CSSProperties> = {
+  sm: { fontSize: 11, padding: '1px 6px' },
+  md: { fontSize: 12, padding: '2px 8px' },
+  lg: { fontSize: 14, padding: '4px 10px' },
+};
+
+const BASE_STYLE: React.CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 4,
+  borderRadius: 9999,
+  fontWeight: 600,
+  lineHeight: 1.4,
+  whiteSpace: 'nowrap',
+};
+
+/** Accessible status badge; forwards all standard span props and a ref. */
+export const Badge = forwardRef<HTMLSpanElement, BadgeProps>(function Badge(
+  { variant = 'default', size = 'md', style, children, ...rest },
+  ref,
+) {
+  return (
+    <span
+      ref={ref}
+      style={{
+        ...BASE_STYLE,
+        ...VARIANT_STYLES[variant],
+        ...SIZE_STYLES[size],
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+});
diff --git a/react/src/components/COMPONENTS.md b/react/src/components/COMPONENTS.md
new file mode 100644
index 0000000..a1694cc
--- /dev/null
+++ b/react/src/components/COMPONENTS.md
@@ -0,0 +1,113 @@
+# @bc-forge/react UI components
+
+Reusable, accessible, dependency-free React components. Each component ships
+with inline styles (no CSS import or Tailwind setup required) and forwards
+standard HTML attributes so it slots into any design system.
+
+```tsx
+import { Badge, Alert, Pagination, Modal, Tooltip } from '@bc-forge/react';
+```
+
+## Badge
+
+Status pill for labels, counts, and states.
+
+| Prop      | Type                                                                  | Default     | Description                          |
+| --------- | --------------------------------------------------------------------- | ----------- | ------------------------------------ |
+| `variant` | `'default' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'default'` | Visual style.                        |
+| `size`    | `'sm' \| 'md' \| 'lg'`                                                 | `'md'`      | Badge size.                          |
+| `...rest` | `React.HTMLAttributes<HTMLSpanElement>`                               | —           | Any span prop (`className`, `aria-*`). |
+
+Renders a `<span>` and forwards a `ref`. Provide `aria-label` when the visible
+text isn't descriptive on its own (e.g. a bare count).
+
+```tsx
+<Badge variant="success">Verified</Badge>
+<Badge variant="danger" size="lg" aria-label="3 failed checks">3</Badge>
+```
+
+## Alert
+
+Inline notification banner. The ARIA role is derived from the variant —
+`danger`/`warning` → `role="alert"` (assertive), `info`/`success` →
+`role="status"` (polite). Pass `role` to override.
+
+| Prop           | Type                                            | Default          | Description                                |
+| -------------- | ----------------------------------------------- | ---------------- | ------------------------------------------ |
+| `variant`      | `'info' \| 'success' \| 'warning' \| 'danger'`  | `'info'`         | Visual + semantic style.                   |
+| `title`        | `React.ReactNode`                               | —                | Optional bold heading.                     |
+| `onDismiss`    | `() => void`                                    | —                | When set, renders a keyboard-focusable dismiss button. |
+| `dismissLabel` | `string`                                        | `'Dismiss alert'`| Accessible label for the dismiss button.   |
+| `...rest`      | `React.HTMLAttributes<HTMLDivElement>`          | —                | Any div prop.                              |
+
+```tsx
+<Alert variant="success" title="Saved">Your changes were stored.</Alert>
+<Alert variant="danger" onDismiss={() => setError(null)}>Mint failed.</Alert>
+```
+
+## Pagination
+
+Page navigation rendered as a `<nav>` landmark with native `<button>`s
+(keyboard-accessible out of the box). The active page carries
+`aria-current="page"`; Previous/Next are `disabled` at the bounds. Returns
+`null` when `totalPages <= 1`.
+
+| Prop           | Type                       | Default        | Description                                   |
+| -------------- | -------------------------- | -------------- | --------------------------------------------- |
+| `currentPage`  | `number`                   | —              | 1-based current page.                         |
+| `totalPages`   | `number`                   | —              | Total page count.                             |
+| `onPageChange` | `(page: number) => void`   | —              | Called with the requested page (clamped).     |
+| `siblingCount` | `number`                   | `1`            | Page buttons shown on each side of current.   |
+| `ariaLabel`    | `string`                   | `'Pagination'` | Label for the `<nav>` landmark.               |
+| `...rest`      | `React.HTMLAttributes<HTMLElement>` | —     | Any element prop (minus `onChange`).          |
+
+The pure helper `getPaginationRange(currentPage, totalPages, siblingCount)` is
+exported for testing/customisation; it returns page numbers with `'dots'`
+sentinels where the range is collapsed.
+
+```tsx
+<Pagination currentPage={page} totalPages={20} onPageChange={setPage} />
+```
+
+## Modal
+
+Accessible dialog with full focus management (WCAG 2.1 AA):
+
+- `role="dialog"`, `aria-modal="true"`, `aria-labelledby` → the title.
+- Moves focus into the dialog on open and **restores** it to the trigger on close.
+- **Traps** Tab / Shift+Tab inside the dialog.
+- Closes on Escape and (optionally) on overlay click.
+
+| Prop                  | Type              | Default          | Description                                  |
+| --------------------- | ----------------- | ---------------- | -------------------------------------------- |
+| `open`                | `boolean`         | —                | Whether the dialog is mounted and visible.   |
+| `onClose`             | `() => void`      | —                | Called on Escape, close button, overlay click.|
+| `title`               | `React.ReactNode` | —                | Dialog heading; also the accessible name.    |
+| `children`            | `React.ReactNode` | —                | Dialog body.                                 |
+| `closeOnOverlayClick` | `boolean`         | `true`           | Close when the backdrop is clicked.          |
+| `closeLabel`          | `string`          | `'Close dialog'` | Accessible label for the header close button.|
+
+```tsx
+<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm mint">
+  <p>Mint 1,000 tokens to G…ABC?</p>
+  <button onClick={confirm}>Confirm</button>
+</Modal>
+```
+
+## Tooltip
+
+Shows contextual text on hover **and** keyboard focus, dismissible with Escape.
+Renders `role="tooltip"` and links the trigger via `aria-describedby`. Wraps a
+single focusable element.
+
+| Prop        | Type                                      | Default | Description                  |
+| ----------- | ----------------------------------------- | ------- | ---------------------------- |
+| `content`   | `React.ReactNode`                         | —       | Tooltip contents.            |
+| `children`  | `React.ReactElement`                      | —       | The (focusable) trigger.     |
+| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'`  | `'top'` | Position relative to trigger.|
+
+```tsx
+<Tooltip content="Copy address">
+  <button onClick={copy}>📋</button>
+</Tooltip>
+```
diff --git a/react/src/components/Modal.tsx b/react/src/components/Modal.tsx
new file mode 100644
index 0000000..3c04546
--- /dev/null
+++ b/react/src/components/Modal.tsx
@@ -0,0 +1,163 @@
+import React, { useCallback, useEffect, useId, useRef } from 'react';
+
+export interface ModalProps {
+  /** Whether the modal is mounted and visible. */
+  open: boolean;
+  /** Called when the user requests to close (Escape key or overlay click). */
+  onClose: () => void;
+  /** Accessible title; rendered as the dialog heading and used for `aria-labelledby`. */
+  title: React.ReactNode;
+  /** Modal body content. */
+  children: React.ReactNode;
+  /** Close when the backdrop behind the dialog is clicked. @default true */
+  closeOnOverlayClick?: boolean;
+  /** Accessible label for the header close button. @default 'Close dialog' */
+  closeLabel?: string;
+}
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not([disabled])',
+  'textarea:not([disabled])',
+  'input:not([disabled])',
+  'select:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+/**
+ * Accessible modal dialog (WCAG 2.1 AA): role="dialog" + aria-modal, focus moved
+ * in on open and restored on close, Tab/Shift+Tab trapped, Escape/overlay close.
+ */
+export function Modal({
+  open,
+  onClose,
+  title,
+  children,
+  closeOnOverlayClick = true,
+  closeLabel = 'Close dialog',
+}: ModalProps) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const previouslyFocused = useRef<HTMLElement | null>(null);
+  const titleId = useId();
+
+  const focusableElements = useCallback((): HTMLElement[] => {
+    const root = dialogRef.current;
+    if (!root) return [];
+    return Array.from(root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+      (el) => el.offsetParent !== null || el === document.activeElement,
+    );
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+
+    previouslyFocused.current = document.activeElement as HTMLElement | null;
+
+    const focusables = focusableElements();
+    (focusables[0] ?? dialogRef.current)?.focus();
+
+    return () => {
+      previouslyFocused.current?.focus?.();
+    };
+  }, [open, focusableElements]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === 'Escape') {
+        event.stopPropagation();
+        onClose();
+        return;
+      }
+
+      if (event.key !== 'Tab') return;
+
+      const focusables = focusableElements();
+      if (focusables.length === 0) {
+        event.preventDefault();
+        dialogRef.current?.focus();
+        return;
+      }
+
+      const first = focusables[0];
+      const last = focusables[focusables.length - 1];
+      const active = document.activeElement;
+
+      if (event.shiftKey && (active === first || active === dialogRef.current)) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && active === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    },
+    [focusableElements, onClose],
+  );
+
+  if (!open) return null;
+
+  return (
+    <div
+      onClick={closeOnOverlayClick ? onClose : undefined}
+      style={{
+        position: 'fixed',
+        inset: 0,
+        background: 'rgba(17, 24, 39, 0.5)',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 16,
+        zIndex: 1000,
+      }}
+    >
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        tabIndex={-1}
+        onClick={(e) => e.stopPropagation()}
+        onKeyDown={handleKeyDown}
+        style={{
+          background: '#ffffff',
+          borderRadius: 12,
+          padding: 20,
+          maxWidth: 480,
+          width: '100%',
+          maxHeight: '90vh',
+          overflowY: 'auto',
+          boxShadow: '0 20px 60px rgba(0,0,0,0.25)',
+        }}
+      >
+        <div
+          style={{
+            display: 'flex',
+            alignItems: 'flex-start',
+            justifyContent: 'space-between',
+            gap: 12,
+            marginBottom: 12,
+          }}
+        >
+          <h2 id={titleId} style={{ margin: 0, fontSize: 18, fontWeight: 700 }}>
+            {title}
+          </h2>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label={closeLabel}
+            style={{
+              border: 'none',
+              background: 'transparent',
+              cursor: 'pointer',
+              fontSize: 20,
+              lineHeight: 1,
+              padding: 2,
+            }}
+          >
+            &times;
+          </button>
+        </div>
+        {children}
+      </div>
+    </div>
+  );
+}
diff --git a/react/src/components/Pagination.tsx b/react/src/components/Pagination.tsx
new file mode 100644
index 0000000..7a2494b
--- /dev/null
+++ b/react/src/components/Pagination.tsx
@@ -0,0 +1,151 @@
+import React from 'react';
+
+const DOTS = 'dots' as const;
+type PageItem = number | typeof DOTS;
+
+export interface PaginationProps
+  extends Omit<React.HTMLAttributes<HTMLElement>, 'onChange'> {
+  /** 1-based index of the current page. */
+  currentPage: number;
+  /** Total number of pages (>= 1). */
+  totalPages: number;
+  /** Called with the requested page number when a control is activated. */
+  onPageChange: (page: number) => void;
+  /** Number of page buttons to show on each side of the current page. @default 1 */
+  siblingCount?: number;
+  /** Accessible label for the surrounding `<nav>` landmark. @default 'Pagination' */
+  ariaLabel?: string;
+}
+
+function range(start: number, end: number): number[] {
+  return Array.from({ length: Math.max(end - start + 1, 0) }, (_, i) => start + i);
+}
+
+export function getPaginationRange(
+  currentPage: number,
+  totalPages: number,
+  siblingCount: number,
+): PageItem[] {
+  const totalPageNumbers = siblingCount * 2 + 5;
+
+  if (totalPages <= totalPageNumbers) {
+    return range(1, totalPages);
+  }
+
+  const leftSibling = Math.max(currentPage - siblingCount, 1);
+  const rightSibling = Math.min(currentPage + siblingCount, totalPages);
+
+  const showLeftDots = leftSibling > 2;
+  const showRightDots = rightSibling < totalPages - 1;
+
+  if (!showLeftDots && showRightDots) {
+    return [...range(1, 3 + 2 * siblingCount), DOTS, totalPages];
+  }
+
+  if (showLeftDots && !showRightDots) {
+    return [1, DOTS, ...range(totalPages - (3 + 2 * siblingCount) + 1, totalPages)];
+  }
+
+  return [1, DOTS, ...range(leftSibling, rightSibling), DOTS, totalPages];
+}
+
+const buttonStyle: React.CSSProperties = {
+  minWidth: 36,
+  height: 36,
+  padding: '0 8px',
+  borderRadius: 8,
+  border: '1px solid #e5e7eb',
+  background: '#ffffff',
+  color: '#374151',
+  fontSize: 14,
+  cursor: 'pointer',
+};
+
+const activeStyle: React.CSSProperties = {
+  borderColor: '#4f46e5',
+  background: '#4f46e5',
+  color: '#ffffff',
+  fontWeight: 600,
+};
+
+const disabledStyle: React.CSSProperties = {
+  opacity: 0.5,
+  cursor: 'not-allowed',
+};
+
+/** Accessible pagination: <nav> landmark, native buttons, aria-current, ellipses. */
+export function Pagination({
+  currentPage,
+  totalPages,
+  onPageChange,
+  siblingCount = 1,
+  ariaLabel = 'Pagination',
+  style,
+  ...rest
+}: PaginationProps) {
+  if (totalPages <= 1) {
+    return null;
+  }
+
+  const goTo = (page: number) => {
+    const next = Math.min(Math.max(page, 1), totalPages);
+    if (next !== currentPage) {
+      onPageChange(next);
+    }
+  };
+
+  const items = getPaginationRange(currentPage, totalPages, siblingCount);
+  const onFirst = currentPage <= 1;
+  const onLast = currentPage >= totalPages;
+
+  return (
+    <nav
+      aria-label={ariaLabel}
+      style={{ display: 'flex', alignItems: 'center', gap: 6, ...style }}
+      {...rest}
+    >
+      <button
+        type="button"
+        onClick={() => goTo(currentPage - 1)}
+        disabled={onFirst}
+        aria-label="Go to previous page"
+        style={{ ...buttonStyle, ...(onFirst ? disabledStyle : null) }}
+      >
+        &lsaquo;
+      </button>
+
+      {items.map((item, index) =>
+        item === DOTS ? (
+          <span
+            key={`dots-${index}`}
+            aria-hidden="true"
+            style={{ minWidth: 24, textAlign: 'center', color: '#9ca3af' }}
+          >
+            &hellip;
+          </span>
+        ) : (
+          <button
+            key={item}
+            type="button"
+            onClick={() => goTo(item)}
+            aria-label={`Go to page ${item}`}
+            aria-current={item === currentPage ? 'page' : undefined}
+            style={{ ...buttonStyle, ...(item === currentPage ? activeStyle : null) }}
+          >
+            {item}
+          </button>
+        ),
+      )}
+
+      <button
+        type="button"
+        onClick={() => goTo(currentPage + 1)}
+        disabled={onLast}
+        aria-label="Go to next page"
+        style={{ ...buttonStyle, ...(onLast ? disabledStyle : null) }}
+      >
+        &rsaquo;
+      </button>
+    </nav>
+  );
+}
diff --git a/react/src/components/Tooltip.tsx b/react/src/components/Tooltip.tsx
new file mode 100644
index 0000000..df27416
--- /dev/null
+++ b/react/src/components/Tooltip.tsx
@@ -0,0 +1,54 @@
+import React, { cloneElement, useId, useState } from 'react';
+
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+
+export interface TooltipProps {
+  content: React.ReactNode;
+  children: React.ReactElement;
+  placement?: TooltipPlacement;
+}
+
+const PLACEMENT_STYLES: Record<TooltipPlacement, React.CSSProperties> = {
+  top: { bottom: '100%', left: '50%', transform: 'translateX(-50%)', marginBottom: 6 },
+  bottom: { top: '100%', left: '50%', transform: 'translateX(-50%)', marginTop: 6 },
+  left: { right: '100%', top: '50%', transform: 'translateY(-50%)', marginRight: 6 },
+  right: { left: '100%', top: '50%', transform: 'translateY(-50%)', marginLeft: 6 },
+};
+
+const tooltipStyle: React.CSSProperties = {
+  position: 'absolute',
+  zIndex: 50,
+  whiteSpace: 'nowrap',
+  borderRadius: 6,
+  background: '#111827',
+  color: '#ffffff',
+  fontSize: 12,
+  padding: '4px 8px',
+  pointerEvents: 'none',
+};
+
+/** Accessible tooltip shown on hover and keyboard focus, dismissible with Escape. */
+export function Tooltip({ content, children, placement = 'top' }: TooltipProps) {
+  const [open, setOpen] = useState(false);
+  const id = useId();
+
+  return (
+    <span
+      style={{ position: 'relative', display: 'inline-flex' }}
+      onMouseEnter={() => setOpen(true)}
+      onMouseLeave={() => setOpen(false)}
+      onFocus={() => setOpen(true)}
+      onBlur={() => setOpen(false)}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') setOpen(false);
+      }}
+    >
+      {cloneElement(children, { 'aria-describedby': open ? id : undefined })}
+      {open ? (
+        <span role="tooltip" id={id} style={{ ...tooltipStyle, ...PLACEMENT_STYLES[placement] }}>
+          {content}
+        </span>
+      ) : null}
+    </span>
+  );
+}
diff --git a/react/src/components/components.test.tsx b/react/src/components/components.test.tsx
new file mode 100644
index 0000000..57ec7b3
--- /dev/null
+++ b/react/src/components/components.test.tsx
@@ -0,0 +1,196 @@
+import '@testing-library/jest-dom';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+
+import { Badge } from './Badge';
+import { Alert } from './Alert';
+import { Pagination, getPaginationRange } from './Pagination';
+import { Modal } from './Modal';
+import { Tooltip } from './Tooltip';
+
+describe('Badge', () => {
+  it('renders its children', () => {
+    render(<Badge>Verified</Badge>);
+    expect(screen.getByText('Verified')).toBeInTheDocument();
+  });
+
+  it('forwards standard HTML props (className, aria-label)', () => {
+    render(
+      <Badge className="custom" aria-label="three failed checks">
+        3
+      </Badge>,
+    );
+    const badge = screen.getByLabelText('three failed checks');
+    expect(badge).toHaveClass('custom');
+  });
+
+  it('forwards a ref to the span element', () => {
+    const ref = React.createRef<HTMLSpanElement>();
+    render(<Badge ref={ref}>x</Badge>);
+    expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+  });
+});
+
+describe('Alert', () => {
+  it('uses role="alert" for danger and warning variants', () => {
+    const { rerender } = render(<Alert variant="danger">boom</Alert>);
+    expect(screen.getByRole('alert')).toHaveTextContent('boom');
+    rerender(<Alert variant="warning">careful</Alert>);
+    expect(screen.getByRole('alert')).toHaveTextContent('careful');
+  });
+
+  it('uses role="status" for info and success variants', () => {
+    render(<Alert variant="success">ok</Alert>);
+    expect(screen.getByRole('status')).toHaveTextContent('ok');
+  });
+
+  it('renders the title and body', () => {
+    render(
+      <Alert title="Saved">Your changes were stored.</Alert>,
+    );
+    expect(screen.getByText('Saved')).toBeInTheDocument();
+    expect(screen.getByText('Your changes were stored.')).toBeInTheDocument();
+  });
+
+  it('renders a dismiss button only when onDismiss is provided', () => {
+    const onDismiss = jest.fn();
+    const { rerender } = render(<Alert>no button</Alert>);
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+
+    rerender(<Alert onDismiss={onDismiss}>with button</Alert>);
+    fireEvent.click(screen.getByRole('button', { name: 'Dismiss alert' }));
+    expect(onDismiss).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('getPaginationRange', () => {
+  it('lists every page when the total fits without collapsing', () => {
+    expect(getPaginationRange(1, 5, 1)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it('collapses the right side near the start', () => {
+    expect(getPaginationRange(1, 10, 1)).toEqual([1, 2, 3, 4, 5, 'dots', 10]);
+  });
+
+  it('collapses the left side near the end', () => {
+    expect(getPaginationRange(10, 10, 1)).toEqual([1, 'dots', 6, 7, 8, 9, 10]);
+  });
+
+  it('collapses both sides in the middle', () => {
+    expect(getPaginationRange(5, 10, 1)).toEqual([1, 'dots', 4, 5, 6, 'dots', 10]);
+  });
+});
+
+describe('Pagination', () => {
+  it('renders nothing for a single page', () => {
+    const { container } = render(
+      <Pagination currentPage={1} totalPages={1} onPageChange={() => {}} />,
+    );
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it('marks the current page with aria-current and disables Previous on page 1', () => {
+    render(<Pagination currentPage={1} totalPages={5} onPageChange={() => {}} />);
+    expect(screen.getByRole('button', { name: 'Go to page 1' })).toHaveAttribute(
+      'aria-current',
+      'page',
+    );
+    expect(screen.getByRole('button', { name: 'Go to previous page' })).toBeDisabled();
+  });
+
+  it('calls onPageChange when a page button is activated', () => {
+    const onPageChange = jest.fn();
+    render(<Pagination currentPage={1} totalPages={5} onPageChange={onPageChange} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Go to page 3' }));
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it('does not fire onPageChange for the already-active page', () => {
+    const onPageChange = jest.fn();
+    render(<Pagination currentPage={2} totalPages={5} onPageChange={onPageChange} />);
+    fireEvent.click(screen.getByRole('button', { name: 'Go to page 2' }));
+    expect(onPageChange).not.toHaveBeenCalled();
+  });
+});
+
+describe('Modal', () => {
+  it('renders nothing when closed', () => {
+    render(
+      <Modal open={false} onClose={() => {}} title="Hidden">
+        body
+      </Modal>,
+    );
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+
+  it('exposes a labelled modal dialog when open', () => {
+    render(
+      <Modal open onClose={() => {}} title="Confirm action">
+        Are you sure?
+      </Modal>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(dialog).toHaveAttribute('aria-modal', 'true');
+    expect(dialog).toHaveAccessibleName('Confirm action');
+  });
+
+  it('moves focus inside the dialog on open', () => {
+    render(
+      <Modal open onClose={() => {}} title="Focus test">
+        <button type="button">Inner action</button>
+      </Modal>,
+    );
+    const dialog = screen.getByRole('dialog');
+    expect(dialog.contains(document.activeElement)).toBe(true);
+  });
+
+  it('calls onClose on Escape and on the close button', () => {
+    const onClose = jest.fn();
+    render(
+      <Modal open onClose={onClose} title="Closable">
+        body
+      </Modal>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Close dialog' }));
+    expect(onClose).toHaveBeenCalledTimes(1);
+
+    fireEvent.keyDown(screen.getByRole('dialog'), { key: 'Escape' });
+    expect(onClose).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('Tooltip', () => {
+  it('is hidden until hovered, then shows with role=tooltip and links the trigger', () => {
+    const { container } = render(
+      <Tooltip content="Help text">
+        <button>trigger</button>
+      </Tooltip>,
+    );
+    const wrapper = container.firstChild as HTMLElement;
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
+
+    fireEvent.mouseEnter(wrapper);
+    const tip = screen.getByRole('tooltip');
+    expect(tip).toHaveTextContent('Help text');
+    expect(screen.getByRole('button', { name: 'trigger' })).toHaveAttribute(
+      'aria-describedby',
+      tip.id,
+    );
+
+    fireEvent.mouseLeave(wrapper);
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
+  });
+
+  it('dismisses on Escape', () => {
+    const { container } = render(
+      <Tooltip content="Help text">
+        <button>trigger</button>
+      </Tooltip>,
+    );
+    const wrapper = container.firstChild as HTMLElement;
+    fireEvent.mouseEnter(wrapper);
+    expect(screen.getByRole('tooltip')).toBeInTheDocument();
+    fireEvent.keyDown(wrapper, { key: 'Escape' });
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
+  });
+});
diff --git a/react/src/components/index.ts b/react/src/components/index.ts
new file mode 100644
index 0000000..565aa46
--- /dev/null
+++ b/react/src/components/index.ts
@@ -0,0 +1,14 @@
+export { Badge } from './Badge';
+export type { BadgeProps, BadgeVariant, BadgeSize } from './Badge';
+
+export { Alert } from './Alert';
+export type { AlertProps, AlertVariant } from './Alert';
+
+export { Pagination, getPaginationRange } from './Pagination';
+export type { PaginationProps } from './Pagination';
+
+export { Modal } from './Modal';
+export type { ModalProps } from './Modal';
+
+export { Tooltip } from './Tooltip';
+export type { TooltipProps, TooltipPlacement } from './Tooltip';
diff --git a/react/src/index.ts b/react/src/index.ts
index 472021f..735a55d 100644
--- a/react/src/index.ts
+++ b/react/src/index.ts
@@ -1,2 +1,4 @@
 export * from './context';
 export * from './hooks';
+export * from './useTokenMetadata';
+export * from './components';
diff --git a/react/src/useTokenMetadata.test.tsx b/react/src/useTokenMetadata.test.tsx
new file mode 100644
index 0000000..096a8e8
--- /dev/null
+++ b/react/src/useTokenMetadata.test.tsx
@@ -0,0 +1,73 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { useTokenMetadata } from './useTokenMetadata';
+import { useBcForgeClient } from './context';
+
+jest.mock('./context', () => ({ useBcForgeClient: jest.fn() }));
+const mockedUseClient = useBcForgeClient as jest.MockedFunction<typeof useBcForgeClient>;
+
+type ClientOverrides = Partial<{
+  getName: jest.Mock;
+  getSymbol: jest.Mock;
+  getDecimals: jest.Mock;
+}>;
+
+function makeClient(overrides: ClientOverrides = {}) {
+  return {
+    getName: jest.fn().mockResolvedValue('BC Forge Token'),
+    getSymbol: jest.fn().mockResolvedValue('BCF'),
+    getDecimals: jest.fn().mockResolvedValue(7),
+    ...overrides,
+  } as unknown as ReturnType<typeof useBcForgeClient>;
+}
+
+describe('useTokenMetadata', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('starts loading, then exposes resolved metadata', async () => {
+    mockedUseClient.mockReturnValue(makeClient());
+    const { result } = renderHook(() => useTokenMetadata({ retryDelayMs: 0 }));
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.data).toEqual({ name: 'BC Forge Token', symbol: 'BCF', decimals: 7 });
+    expect(result.current.error).toBeNull();
+  });
+
+  it('surfaces an error when the client rejects', async () => {
+    mockedUseClient.mockReturnValue(
+      makeClient({ getName: jest.fn().mockRejectedValue(new Error('RPC down')) }),
+    );
+    const { result } = renderHook(() => useTokenMetadata({ retries: 1, retryDelayMs: 0 }));
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.error?.message).toBe('RPC down');
+    expect(result.current.data).toBeNull();
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  it('retries a transient failure before succeeding', async () => {
+    const getName = jest
+      .fn()
+      .mockRejectedValueOnce(new Error('transient'))
+      .mockResolvedValue('BC Forge Token');
+    mockedUseClient.mockReturnValue(makeClient({ getName }));
+    const { result } = renderHook(() => useTokenMetadata({ retries: 2, retryDelayMs: 0 }));
+
+    await waitFor(() => expect(result.current.data).not.toBeNull());
+    expect(getName).toHaveBeenCalledTimes(2);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('caches metadata so a remount does not re-fetch', async () => {
+    const client = makeClient();
+    mockedUseClient.mockReturnValue(client);
+
+    const first = renderHook(() => useTokenMetadata({ retryDelayMs: 0 }));
+    await waitFor(() => expect(first.result.current.data).not.toBeNull());
+    expect((client.getName as jest.Mock)).toHaveBeenCalledTimes(1);
+
+    const second = renderHook(() => useTokenMetadata({ retryDelayMs: 0 }));
+    await waitFor(() => expect(second.result.current.data).not.toBeNull());
+    expect((client.getName as jest.Mock)).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/react/src/useTokenMetadata.ts b/react/src/useTokenMetadata.ts
new file mode 100644
index 0000000..ef20a07
--- /dev/null
+++ b/react/src/useTokenMetadata.ts
@@ -0,0 +1,93 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useBcForgeClient } from './context';
+
+export interface TokenMetadata {
+  name: string;
+  symbol: string;
+  decimals: number;
+}
+
+export interface UseTokenMetadataOptions {
+  retries?: number;
+  retryDelayMs?: number;
+}
+
+export interface UseTokenMetadataResult {
+  data: TokenMetadata | null;
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+
+const tokenMetadataCache = new WeakMap<object, TokenMetadata>();
+
+async function withRetry<T>(fn: () => Promise<T>, retries: number, delayMs: number): Promise<T> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+      if (attempt < retries && delayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  throw lastError;
+}
+
+/**
+ * Fetch token metadata (name, symbol, decimals) with loading/error state,
+ * per-client caching, and retry on transient RPC failures.
+ */
+export function useTokenMetadata(
+  { retries = 2, retryDelayMs = 300 }: UseTokenMetadataOptions = {},
+): UseTokenMetadataResult {
+  const client = useBcForgeClient();
+  const [data, setData] = useState<TokenMetadata | null>(
+    () => tokenMetadataCache.get(client as object) ?? null,
+  );
+  const [isLoading, setIsLoading] = useState(!tokenMetadataCache.has(client as object));
+  const [error, setError] = useState<Error | null>(null);
+
+  const load = useCallback(
+    async (force: boolean) => {
+      if (!force) {
+        const cached = tokenMetadataCache.get(client as object);
+        if (cached) {
+          setData(cached);
+          setIsLoading(false);
+          return;
+        }
+      }
+
+      setIsLoading(true);
+      setError(null);
+      try {
+        const [name, symbol, decimals] = await withRetry(
+          () => Promise.all([client.getName(), client.getSymbol(), client.getDecimals()]),
+          retries,
+          retryDelayMs,
+        );
+        const metadata: TokenMetadata = { name, symbol, decimals };
+        tokenMetadataCache.set(client as object, metadata);
+        setData(metadata);
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [client, retries, retryDelayMs],
+  );
+
+  useEffect(() => {
+    void load(false);
+  }, [load]);
+
+  const refetch = useCallback(() => {
+    void load(true);
+  }, [load]);
+
+  return { data, isLoading, error, refetch };
+}