Visual Editor

The Visual Editor is the heart of Onlook’s user experience, providing a comprehensive visual development environment that bridges the gap between design tools and code editors. It enables users to create and modify web applications through direct manipulation, intuitive panels, and powerful editing tools, all while maintaining the precision and flexibility of code-based development.

Product Specifications

User Experience Flow

The visual editing experience in Onlook is designed around direct manipulation and contextual interfaces. Users interact with their web applications visually while the system maintains perfect synchronization with the underlying code, creating a seamless bridge between visual design and development.

Functional Requirements

Feature	End-to-End Business Logic and Rules
Left Panel Navigation System	User Intent: To access and manage all project resources and structure through an organized, intuitive interface. End-to-End Flow: 1. System - Panel Structure: The left panel features five distinct tabs, each serving a specific project management function. Users can access Layers (element hierarchy), Brand (design system), Pages (navigation structure), Images (asset management), and Branches (version control). 2. Frontend - Interaction Model: The panel supports two interaction modes: hover-to-preview and click-to-lock. When users hover over a tab, it temporarily opens to show content. When they click, the panel locks open for extended interaction, allowing deep work within that section. 3. System - Dynamic Content Loading: Each tab loads and displays relevant project data in real-time. The Layers tab shows the current page’s element hierarchy, Brand tab displays active design tokens, Pages tab lists all project routes, Images tab shows uploaded assets, and Branches tab displays version control status. 4. Frontend - Responsive Behavior: The panel automatically adjusts its width and content density based on available screen space, ensuring usability across different device sizes while maintaining access to all functionality. Key Rules & Constraints: - Only one tab can be locked open at a time to maintain interface clarity. - Panel content updates automatically when the active page or selection changes. - The system preserves user preferences for panel state across sessions.
Layers Management System	User Intent: To understand, navigate, and manipulate the hierarchical structure of web page elements in a visual, tree-like interface. End-to-End Flow: 1. System - Hierarchy Visualization: The layers panel displays all page elements in a tree structure that mirrors the DOM hierarchy. Each element is represented with its tag name, classes, and nesting level, providing a clear understanding of the page structure. 2. Frontend - Interactive Selection: Users can click on any element in the layers panel to select it in both the panel and the main canvas. The selected element becomes highlighted with visual indicators, and its properties become available for editing. 3. System - Bidirectional Synchronization: When users select an element in the canvas, the layers panel automatically scrolls to and highlights the corresponding item in the hierarchy. This ensures users always understand their current context within the page structure. 4. Frontend - Structural Operations: The panel supports drag-and-drop reordering of elements, allowing users to restructure their page hierarchy visually. It also provides context menus for common operations like duplicating, deleting, or grouping elements. Key Rules & Constraints: - The hierarchy always reflects the actual DOM structure to maintain code accuracy. - Only valid structural modifications are allowed to prevent breaking the application. - The system prevents users from creating invalid HTML structures through the visual interface.
Brand Asset Management	User Intent: To maintain consistent visual identity across the project by managing colors, fonts, and design tokens in a centralized system. End-to-End Flow: 1. System - Design Token Discovery: The brand panel automatically scans the project’s codebase to identify and extract existing design tokens, including colors used in Tailwind classes, custom CSS variables, and font definitions. 2. Frontend - Visual Token Library: All discovered design elements are displayed in an organized, visual format. Colors appear as swatches with their values, fonts show sample text, and spacing values are represented with visual indicators. 3. System - Global Application: When users select a design token from the brand panel, they can apply it to selected elements with a single click. The system automatically updates the appropriate CSS classes or properties to implement the change. 4. Frontend - Token Creation: Users can create new design tokens directly through the brand panel. New colors, font combinations, or spacing values become immediately available for use throughout the project and are automatically integrated into the codebase. Key Rules & Constraints: - All brand changes automatically update throughout the project to maintain consistency. - The system preserves the relationship between visual tokens and their underlying code representations. - New tokens follow the project’s existing naming conventions and structure.
Page Navigation Management	User Intent: To create, organize, and navigate between different pages within the web application project. End-to-End Flow: 1. System - Route Discovery: The pages panel automatically detects all routes in the Next.js project by scanning the file system structure and identifying page components, displaying them in an organized tree that reflects the URL structure. 2. Frontend - Visual Navigation: Each page is displayed with its route path, title, and a thumbnail preview. Users can click on any page to immediately switch their editing context to that page, with the canvas and all panels updating to reflect the new page’s content. 3. System - Page Creation Workflow: Users can create new pages through a guided interface that handles both the file system operations (creating the appropriate files and folders) and the routing configuration (ensuring proper Next.js route setup). 4. Frontend - Page Management: The panel provides options for renaming pages, organizing them into folders, setting up nested routes, and managing page metadata like titles and descriptions. Key Rules & Constraints: - All page operations maintain valid Next.js routing conventions. - The system prevents creating duplicate routes or invalid URL structures. - Page changes are immediately reflected in the project’s navigation and file structure.
Image Asset Management	User Intent: To upload, organize, and use images and other media assets efficiently within the web application. End-to-End Flow: 1. System - Asset Upload & Processing: Users can upload images through drag-and-drop or file selection. The system automatically processes uploaded images, generating optimized versions for web use and creating appropriate file paths within the project structure. 2. Frontend - Visual Asset Library: All project images are displayed in a grid view with thumbnails, file names, sizes, and usage information. Users can preview images at full size and see where each image is currently used within the project. 3. System - Smart Integration: When users drag an image from the asset panel to the canvas, the system automatically generates the appropriate HTML image element with proper src attributes, alt text prompts, and responsive sizing classes. 4. Frontend - Asset Organization: Users can organize images into folders, rename files, and delete unused assets. The system provides warnings when attempting to delete images that are currently in use within the project. Key Rules & Constraints: - All uploaded images are automatically optimized for web performance. - The system maintains references between images and their usage locations. - Asset operations preserve the integrity of existing image references in the codebase.
Version Control Interface	User Intent: To manage project versions, create experimental branches, and track changes without complex command-line operations. End-to-End Flow: 1. System - Branch Visualization: The branches panel displays all project branches in a visual tree structure, showing the relationship between branches, recent commits, and current status. Each branch is represented with its name, last modified date, and a brief description of changes. 2. Frontend - Branch Operations: Users can create new branches for experimentation, switch between existing branches, and merge changes back to the main branch through simple click operations. The interface provides clear indicators of which branch is currently active. 3. System - Change Tracking: The system automatically tracks all modifications made through the visual editor, creating meaningful commit messages that describe the visual changes in human-readable terms (e.g., “Updated button color in hero section”). 4. Frontend - Conflict Resolution: When branch conflicts occur, the system presents them in a visual format, allowing users to choose between different versions of components or merge changes through guided workflows. Key Rules & Constraints: - All visual changes are automatically tracked and committed with descriptive messages. - The system prevents data loss by requiring explicit confirmation for destructive operations. - Branch operations maintain the integrity of the project structure and dependencies.
Interactive Canvas System	User Intent: To directly manipulate web page elements through clicking, dragging, and visual interaction within a live preview environment. End-to-End Flow: 1. System - Live Preview Rendering: The canvas displays a fully functional version of the web application, updated in real-time as changes are made. This preview is interactive, allowing users to test functionality while editing. 2. Frontend - Element Selection: Users can click on any element within the canvas to select it. Selected elements are highlighted with visual indicators including selection borders, resize handles, and contextual information tooltips. 3. System - Direct Manipulation: Selected elements can be moved by dragging, resized using handles, and modified through direct interaction. The system translates these visual operations into appropriate code changes, maintaining the relationship between visual actions and underlying implementation. 4. Frontend - Contextual Feedback: The canvas provides immediate visual feedback for all interactions, including hover states, selection indicators, snap guides for alignment, and preview overlays for potential drop locations during drag operations. Key Rules & Constraints: - All canvas interactions must maintain valid HTML structure and CSS properties. - Visual manipulations are constrained by the parent element’s layout rules. - The system provides clear feedback when operations cannot be completed due to structural constraints.
Dynamic Editor Toolbar	User Intent: To access relevant editing controls that appear contextually based on the currently selected element or editing task. End-to-End Flow: 1. System - Contextual Tool Detection: When an element is selected, the system analyzes its properties and determines which editing tools are relevant. Text elements show typography controls, layout containers show spacing and alignment tools, and interactive elements show state and behavior options. 2. Frontend - Intelligent Positioning: The toolbar appears near the selected element but positions itself to avoid blocking important content. It uses smart positioning algorithms to stay visible while not interfering with the editing workflow. 3. System - Real-time Property Editing: All toolbar controls are directly connected to the element’s properties. Changes made through toolbar controls immediately update both the visual representation and the underlying code, providing instant feedback. 4. Frontend - Grouped Control Interface: Related controls are grouped together logically (typography, layout, colors, effects), with expandable sections for advanced properties. The interface adapts its complexity based on the user’s expertise level and current needs. Key Rules & Constraints: - Toolbar controls only show options that are valid for the selected element type. - All changes made through the toolbar are immediately reversible through the undo system. - The toolbar automatically hides when not needed to maintain a clean interface.
Element Insertion System	User Intent: To add new elements to the page through intuitive drag-and-drop operations or contextual insertion methods. End-to-End Flow: 1. System - Component Library Access: Users can access a library of available components and elements through the toolbar or dedicated panel. This includes basic HTML elements, common UI components, and custom project components. 2. Frontend - Drag-and-Drop Insertion: Users can drag elements from the component library directly onto the canvas. During the drag operation, the system shows potential drop zones with visual indicators, helping users understand where the new element can be placed. 3. System - Smart Placement Logic: When an element is dropped, the system automatically determines the appropriate parent container and insertion position based on the drop location and the element’s characteristics. It ensures valid HTML structure while respecting design patterns. 4. Frontend - Immediate Editing Mode: Newly inserted elements automatically enter edit mode, allowing users to immediately customize their content, styling, or properties without additional clicks or navigation. Key Rules & Constraints: - New elements can only be inserted in locations that maintain valid HTML structure. - The system prevents insertion of elements that would break the page layout or functionality. - All inserted elements include default styling that matches the project’s design system.
Right-Click Context Menu	User Intent: To access element-specific actions and shortcuts through familiar right-click interactions. End-to-End Flow: 1. Frontend - Context Detection: When users right-click on an element in the canvas, the system analyzes the element type and current context to determine which actions are available and relevant for that specific situation. 2. System - Dynamic Menu Generation: The context menu is generated dynamically based on the selected element’s properties and capabilities. Common actions include copy, paste, duplicate, delete, and element-specific operations like “Edit Text” or “Change Image”. 3. Frontend - Action Execution: Menu items trigger immediate actions when clicked, with appropriate confirmations for destructive operations. The menu provides keyboard shortcuts for power users and clear icons for visual recognition. 4. System - Contextual Workflows: Some menu items launch specialized workflows, such as opening the image selector when “Change Image” is selected, or entering text editing mode when “Edit Text” is chosen. Key Rules & Constraints: - Context menus only show actions that are valid and safe for the selected element. - Destructive actions require confirmation to prevent accidental data loss. - Menu items are organized logically with separators between different action categories.
Zoom and Navigation Controls	User Intent: To navigate and examine the design at different scales, from overview to pixel-perfect detail work. End-to-End Flow: 1. Frontend - Multi-Scale Navigation: Users can zoom in and out of the canvas using mouse wheel, keyboard shortcuts, or dedicated zoom controls. The system maintains smooth zooming with appropriate limits to ensure usability at all scales. 2. System - Adaptive Interface Scaling: As zoom levels change, the interface adapts to maintain usability. At high zoom levels, selection indicators and handles remain appropriately sized, while at low zoom levels, fine details are simplified to maintain performance. 3. Frontend - Pan and Navigate: Users can pan around the canvas by dragging with the space key held, or using dedicated navigation controls. The system provides a mini-map or overview for large pages to help users orient themselves. 4. System - Zoom Context Preservation: The system remembers zoom levels and positions for different pages and editing contexts, allowing users to return to their preferred view when switching between tasks. Key Rules & Constraints: - Zoom levels are constrained to maintain usability and performance. - The interface remains fully functional at all supported zoom levels. - Navigation controls are always accessible regardless of zoom or pan position.

Technical Solution

Natural Language Technical Solution

The Visual Editor operates as a sophisticated layer above the web application’s live preview, providing direct manipulation capabilities while maintaining perfect synchronization with the underlying code structure.

The system uses a multi-panel architecture where each panel serves a specific function in the editing workflow. The Left Panel System acts as the primary navigation and resource management hub, with five specialized tabs that provide access to different aspects of the project. Each tab loads its content dynamically and updates in real-time as the project changes.

The Interactive Canvas serves as the main editing surface, displaying a live, fully-functional version of the web application. This canvas is not just a preview but a fully interactive environment where users can click, drag, and manipulate elements directly. The system captures these interactions and translates them into appropriate code modifications through a sophisticated event handling system.

The Dynamic Editor Toolbar appears contextually when elements are selected, providing relevant editing controls without cluttering the interface. This toolbar uses intelligent positioning algorithms to stay visible and accessible while avoiding interference with the user’s work.

All visual operations are immediately synchronized with the underlying code structure through a bidirectional binding system that ensures visual changes result in proper code modifications and code changes are immediately reflected in the visual interface.

End-to-end Execution Sequence Diagram

Visual Editor Replication & Reference

Visual Editor Replication Guide

Prompt

You are an expert UI/UX engineer. Your task is to create a comprehensive visual editing environment for web applications. The system must provide direct manipulation capabilities, organized resource management, and seamless code synchronization.
 
**Core Feature: Multi-Panel Visual Editor**
 
**1. Left Panel Navigation System:**
- Create a tabbed interface with five main sections: Layers, Brand, Pages, Images, and Branches
- Implement hover-to-preview and click-to-lock interaction patterns
- Each tab should load and display relevant project data dynamically
- Support responsive behavior that adapts to different screen sizes
 
**2. Interactive Canvas System:**
- Build a live preview environment that displays the actual web application
- Implement element selection through click interactions with visual highlighting
- Support drag-and-drop operations for moving and resizing elements
- Provide real-time feedback for all user interactions
 
**3. Dynamic Editor Toolbar:**
- Create contextual toolbars that appear based on selected element types
- Group related controls logically (typography, layout, colors, effects)
- Implement intelligent positioning to avoid blocking important content
- Connect all controls directly to element properties for real-time updates
 
**4. Layers Management:**
- Display page elements in a hierarchical tree structure
- Support bidirectional selection between layers panel and canvas
- Enable drag-and-drop reordering of elements
- Provide context menus for common operations
 
**5. Asset Management Systems:**
- Build visual libraries for images, colors, fonts, and design tokens
- Support drag-and-drop integration from asset panels to canvas
- Implement upload, organization, and optimization workflows
- Maintain usage tracking and reference integrity
 
**Acceptance Criteria:**
1. Users can select any element by clicking in the canvas or layers panel
2. Selected elements show contextual editing controls in a dynamic toolbar
3. All visual changes immediately reflect in both the preview and underlying code
4. The left panel provides organized access to all project resources
5. The interface adapts responsively to different screen sizes and zoom levels

Functional Role	Code File	Description
Main Editor Interface	`apps/web/client/src/app/project/[id]/_components/main.tsx`	The primary editor workspace that orchestrates all visual editing components.
Left Panel System	`apps/web/client/src/app/project/[id]/_components/left-panel/index.tsx`	Multi-tab navigation system providing access to layers, brand, pages, images, and branches.
Interactive Canvas	`apps/web/client/src/app/project/[id]/_components/canvas/index.tsx`	Live preview environment with direct manipulation capabilities for visual editing.
Editor Toolbar	`apps/web/client/src/app/project/[id]/_components/editor-bar/index.tsx`	Contextual editing controls that appear dynamically based on selected elements.
Layers Management	`apps/web/client/src/components/store/editor/element/index.ts`	Element hierarchy management and selection state handling.
Canvas Manager	`apps/web/client/src/components/store/editor/canvas/index.ts`	Canvas interaction handling, zoom controls, and visual feedback systems.
Frame Management	`apps/web/client/src/components/store/editor/frames/index.ts`	Multi-frame support for different device sizes and responsive design testing.
Style Management	`apps/web/client/src/components/store/editor/style/index.ts`	Visual style editing capabilities and CSS property manipulation.
Insert Operations	`apps/web/client/src/components/store/editor/insert/index.ts`	Element insertion logic for drag-and-drop and contextual element addition.
Move Operations	`apps/web/client/src/components/store/editor/move/index.ts`	Element positioning and drag-and-drop movement handling.

AI Code Gen Real-time Preview