uighost-react

v1.1.0

Published

5 days ago

Overlay your Figma designs directly on your live localhost — catch pixel-perfect misalignments instantly.

0High
0Medium
0Low

ossama_dev

ui ghost devtool react figma overlay pixel-perfect visual-testing frontend design-review dom-scanner

uighost-react

Overlay your Figma designs directly on your live localhost. Catch pixel-perfect misalignments, color deviations, and spacing errors instantly — without leaving your browser.

✨ Features

🔍 Overlay Inspector — Load any image URL (Figma export, screenshot) and overlay it directly on your live UI with adjustable opacity and blend modes.
🎨 Figma API Integration — Paste a direct Figma URL and the tool will instantly fetch the frame for you (requires a Figma Personal Access Token).
⌨️ Keyboard Precision — Nudge your overlay pixel-by-pixel using Alt + Arrow Keys to get mathematically perfect alignment.
🎯 Component Scoping — Target a specific CSS selector (like #my-card) to anchor and mask the overlay to just one isolated component.
🔍 Retina Scaling — Instantly scale down @2x retina images from Figma to perfectly fit 1x CSS browser pixels.
📱 Mobile & Touch Support — Drag the DevTool, scroll elements, and scan the DOM straight from your mobile emulator or touch device.
📐 Auto-match Viewport — Load Desktop, Tablet, and Mobile frames simultaneously. The tool instantly switches the active overlay to match your browser width as you resize!
🎨 Custom Themes — Personalize the DOM Scanner's color scheme (Green, Blue, Purple, Rose, Amber) to match your app or brand.
🧩 DOM Scanner — Hover over any element to see its computed CSS (padding, margin, font-size) rendered as a live tooltip.
🎛️ Animated DevTool Panel — A sleek floating ghost icon that springs open into a full control panel.
⚡ Zero-config — No build plugins, no config files. Drop in two lines and you're auditing.
🚫 Dev-only — The tool is designed to be conditionally rendered only in development mode. Nothing ships to production.

📦 Installation

npm install uighost-react --save-dev
# or
pnpm add -D uighost-react
# or
yarn add -D uighost-react

🚀 Quick Start

1. Wrap your app with the Provider

Add UIGhostProvider and UIGhostDevTool to your root layout. Import the styles too.

Vite / React (main.tsx)

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import { UIGhostProvider, UIGhostDevTool } from "uighost-react";
import "uighost-react/dist/styles.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <UIGhostProvider>
      <App />
      {/* Only rendered in development — safe to commit */}
      {import.meta.env.DEV && <UIGhostDevTool />}
    </UIGhostProvider>
  </React.StrictMode>,
);

Next.js (app/layout.tsx)

import { UIGhostProvider, UIGhostDevTool } from "uighost-react";
import "uighost-react/dist/styles.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <UIGhostProvider>
          {children}
          {process.env.NODE_ENV === "development" && <UIGhostDevTool />}
        </UIGhostProvider>
      </body>
    </html>
  );
}

2. Run your dev server

npm run dev

Look for the 👻 ghost icon in the bottom-right corner of your browser.

🎮 Usage

Connection Tab

Paste any publicly accessible image URL (e.g., a Figma frame export via "Copy link") into the Connection panel.
Assign a Viewport tag (Desktop, Tablet, Mobile) to the image.
Enable Auto-match to have UI Ghost automatically display the correct frame as you resize your browser window!

Overlay Tab

Adjust Opacity to blend the design on top of your live UI.
Toggle Blend Mode for different comparison styles.
Use X/Y Offset sliders to fine-tune the alignment.

Scanner Tab

Enable the DOM Scanner to hover over any element and inspect its computed CSS values in real-time.
Change the Theme Color of the scanner to beautifully match your host app's branding.

Advanced Features

Figma API Integration: To paste direct Figma URLs instead of raw image links, you must provide a Figma Personal Access Token.
1. Go to Figma and log in.
2. Visit Settings > Account > Personal Access Tokens.
3. Generate a new token and give it a name (e.g. UI Ghost Local).
4. Paste this token into the UI Ghost ⚙️ Settings modal.
Keyboard Nudging: With the panel open, hold Alt and use Arrow Keys to nudge the overlay by 1px at a time. Hold Alt + Shift for 10px nudges.
Component Scoping: In the Overlays tab, type a CSS selector (e.g., #hero-section) to crop and anchor the design exclusively to that element.
Retina Scaling: Use the "Image Scale" slider to shrink 2x retina handoffs down to exactly 50% so they map perfectly to your browser's pixel space.

🔗 Accessing the Context

You can also programmatically open the DevTool from anywhere in your app using the useUIGhost hook:

import { useUIGhost } from "uighost-react";

export function MyButton() {
  const { setIsOpen } = useUIGhost();

  return <button onClick={() => setIsOpen(true)}>Open UI Ghost</button>;
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

uighost-react

✨ Features

📦 Installation

🚀 Quick Start

1. Wrap your app with the Provider

2. Run your dev server

🎮 Usage

Connection Tab

Overlay Tab

Scanner Tab

Advanced Features

🔗 Accessing the Context

📄 License