Visual Truth

View saved version →

---
name: visual-truth
description: Add and operate the Visual Truth development editor in compatible React websites and web apps. Use when the user asks to visually select, drag, resize, reposition, restyle, or edit live page elements; wants a Duda, Squarespace, Elementor, or general WYSIWYG workflow in Codex; wants exact desktop, iPad, and phone previews; or supplies a Visual Truth change brief that must be translated into durable source code.
---

# Visual Truth

Use the bundled development-only editor to let the user establish visual truth with the mouse, then translate the captured values into maintainable source code.

## Install

1. Inspect the project before editing. Confirm it is a local React web project and identify its package manager, app entry, styling system, and development guard pattern.
2. Run the plugin installer with the project root:

```bash
node <plugin-root>/skills/visual-truth/scripts/install-visual-truth.mjs <project-root>
```

For conventional Vite projects, the installer also configures the local-only Make It Code bridge and generated patch runtime. Preserve those imports; the Vite plugin runs only during local development, while the generated patch module contains the durable visual result.

After a successful installation, the installer makes one best-effort anonymous request containing only the event type and Visual Truth version. It does not transmit project names, paths, source code, page content, accounts, cookies, device identifiers, or editor activity, and analytics failure never fails or rolls back installation. Set `VISUAL_TRUTH_ANALYTICS=0` before running the installer when the user opts out.

3. Create a development-only module for the component and its stylesheet:

```tsx
// src/visual-truth.dev.tsx
import { createRoot } from 'react-dom/client'
import { VisualTruth } from 'visual-truth'
import 'visual-truth/style.css'

export function mountVisualTruth() {
  const host = document.createElement('div')
  host.dataset.visualTruthHost = ''
  document.body.append(host)
  createRoot(host).render(<VisualTruth />)
}
```

Keep Visual Truth in this dedicated host rather than rendering it inside the application's root. While mounted, the component promotes the host into the browser top layer and uses a maximum-z-index fallback when the Popover API is unavailable, so host-site stacking contexts cannot cover the editor or launcher.

Load that module only inside Vite's development branch:

```tsx
if (import.meta.env.DEV) {
  void import('./visual-truth.dev').then(({ mountVisualTruth }) => mountVisualTruth())
}
```

For Next.js, use a client component that is dynamically imported with server-side rendering disabled and gated by `process.env.NODE_ENV !== 'production'`. Preserve the project's existing architecture. Never statically import the editor or its stylesheet from a production application path.

4. Start the existing local development server and open the app in the Codex in-app browser. Do not use the user's personal Chrome session.

## Operate

- Choose the persistent **Workspace** preset that matches the user's preferred editor: Duda adds a familiar left tool rail, Squarespace uses a restrained canvas-first light workspace, and Elementor places Design on the left with Structure/Layers on the right. All three presets keep the same Visual Truth selection, history, responsive scope, and Make It Code behavior.
- Right-click the top toolbar or Duda tool rail to open **Toolbar display**. Turn **Show icon labels** on to place readable names below the toolbar icons, or leave the toolbar compact and use **Use hover hints** for rollover descriptions. Both choices persist across reloads. Labels appear at desktop and iPad-landscape widths; iPad portrait and phone stay compact so every primary action remains on-screen without horizontal toolbar scrolling.
- Work in the attached editing shell: the live site is contained in the center canvas, contextual controls remain docked around it, tools are at the top, 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 45 — file references are metadata, not package contents.