Usar o workspace

AskCodi UI Builder

A user guide for AskCodi's browser-based UI Builder/Sandbox, covering the interface, AI file operations, UI Intent governance, version control, CDN management, and project export features.

What is the AskCodi's UI Builder/Sandbox?

The AskCodi's UI Builder or Sandbox is a browser-based live preview environment where your AI-generated code runs in real-time. It uses Sandpack v2 from CodeSandbox, giving you a full React development environment without any backend setup. Every code change you make through AI chat is instantly reflected in the preview.

The ui builder runs entirely in your browser. No cloud servers, no API keys required, no usage limits. This makes it perfect for rapid prototyping, learning, and building frontend applications with AI assistance.

How the UI builder Works

When you create a new app in UI builder, the UI builder starts with a basic React application structure. As you chat with the AI and request features, the AI generates code using file operation tools. These tools create, update, or delete files in the UI builder, and the preview updates automatically.

The UI builder Interface

The UI builder interface has four main sections: the chat panel, the preview area, the file explorer, and the control bar.

Chat Panel (Left Side)

This is where you interact with the AI. Type natural language requests and the AI generates code. Each message shows:

Your prompt text
AI's response with reasoning
Tool call accordions showing file operations
Intent classification badges (when UI Intent is enabled)

The chat automatically scrolls to show new messages. Previous messages remain visible for context. You can scroll up to review the entire conversation history.

Preview Area (Center/Right)

The preview shows your running application. It updates automatically when the AI modifies files. The preview supports:

Live reloading when code changes
Full React interactivity (state, events, routing)
Mobile-responsive testing (resize your browser)
Error boundaries for runtime errors

If the preview shows a blank screen, check the Console tab for errors. Common issues include syntax errors, missing imports, or runtime exceptions.

Control Bar (Top)

The control bar contains:

View mode selector (Preview | Console | Split View | Files)
Refresh button (reloads the preview manually)
Download button (exports project as ZIP)
Version selector (switch between code versions)
Intent status badge (shows UI Intent governance state)

File Count Badge

The Files tab shows a badge with the current file count (e.g., "Files (3)"). This helps you track how many files the AI has generated.

Four View Modes Explained

The UI builder offers four view modes optimized for different development tasks.

Preview Mode

Preview mode shows only your running application. Use this when:

You want to see the full UI without distractions
You're testing user interactions and flows
You're presenting the app to stakeholders
You need maximum screen space for the preview

Click "Preview" in the control bar to activate this mode. The preview fills the entire UI builder area.

Console Mode

Console mode shows real-time JavaScript console output. Use this when:

You're debugging with console.log() statements
You need to see runtime errors with stack traces
You're tracking variable values during execution
You're checking for warnings or deprecation notices

The console displays four types of messages:

🔵 Info - Regular console.log output (blue)
🟡 Warning - console.warn output (yellow)
🔴 Error - Runtime errors and console.error (red)
⚪ Log - Other console methods (default)

Console output appears as your code runs. Messages include timestamps and can be cleared using the console's clear button.

Split View Mode

Split view shows preview and console side-by-side. Use this when:

You're actively developing and need to see both output and logs
You're debugging UI issues that log errors
You want to monitor console output while testing interactions
You need to verify that code changes produce expected logs

This is the most useful mode for active development. The split is 50/50 by default but can feel cramped on smaller screens.

Files Mode

Files mode shows your project's file tree with a code editor. Use this when:

You want to inspect AI-generated code
You need to copy specific files or code snippets
You're learning how the AI structured your project
You want to understand file organization

The file explorer shows a hierarchical tree structure. Click any file to view its contents with syntax highlighting. Files are read-only in this view—all edits must come from AI chat requests.

File Operations: The AI's Toolbox

The AI has access to six file operation tools. These tools are how the AI actually builds your application.

create_file Tool

Creates a new file with specified content. The AI uses this for:

Initial project files (App.js, index.js, styles.css)
New components (components/Button.js)
New pages (pages/Dashboard.js)
Configuration files (jsconfig.json)

Example AI tool call:

{
  "tool_name": "create_file",
  "arguments": {
    "file_path": "components/Button.js",
    "content": "export default function Button({ children, onClick }) {\n  return (\n    <button onClick={onClick}>\n      {children}\n    </button>\n  );\n}"
  }
}

After execution, you'll see a green accordion in the chat showing the created file with syntax-highlighted code preview.

update_file Tool

Modifies an existing file's content. The AI uses this for:

Refining existing components
Adding new functions to files
Fixing bugs in generated code
Updating styles or configurations

Example AI tool call:

{
  "tool_name": "update_file",
  "arguments": {
    "file_path": "App.js",
    "content": "// Updated App.js with new header\nimport Header from './components/Header';\n\nfunction App() {\n  return (\n    <div>\n      <Header />\n      <main>Content</main>\n    </div>\n  );\n}"
  }
}

You'll see a blue accordion showing the updated file. The tool replaces the entire file content, not just specific lines.

delete_file Tool

Removes a file from the project. The AI uses this for:

Removing unused components
Cleaning up temporary files
Restructuring project organization
Deleting files that conflict with new architecture

Example AI tool call:

{
  "tool_name": "delete_file",
  "arguments": {
    "file_path": "components/OldButton.js"
  }
}

A red accordion appears showing the deleted file path. The file is immediately removed from the UI builder and won't appear in the file tree.

read_file Tool

Reads a file's current content. The AI uses this for:

Understanding existing code before making changes
Checking current implementation details
Verifying file structure before refactoring
Inspecting dependencies or imports

Example AI tool call:

{
  "tool_name": "read_file",
  "arguments": {
    "file_path": "components/Button.js"
  }
}

A purple accordion appears showing the file's content. This tool doesn't modify anything—it just retrieves information for the AI's context.

Bulk Operations (create_files, update_files, delete_files)

These tools handle multiple file operations at once. The AI uses bulk operations when:

Creating a new multi-component feature
Refactoring multiple related files
Setting up initial project structure
Cleaning up multiple unused files

Example bulk create:

{
  "tool_name": "create_files",
  "arguments": {
    "files": [
      {
        "file_path": "components/Header.js",
        "content": "export default function Header() { ... }"
      },
      {
        "file_path": "components/Footer.js",
        "content": "export default function Footer() { ... }"
      },
      {
        "file_path": "components/Sidebar.js",
        "content": "export default function Sidebar() { ... }"
      }
    ]
  }
}

Bulk operations appear as single accordions with collapsible file lists. This keeps the chat clean when the AI creates many files at once.

UI Intent: Design Governance System

UI Intent is a structured contract that governs all AI code generation in your app. It defines what your app should be, how it should look, and what it must not include.

What UI Intent Controls

UI Intent specifies:

Product Type - landing_page, dashboard, saas_app, or internal_tool
Audience - Who uses this app and their experience level
Design Tone - minimal, professional, playful, or bold
Visual Density - compact, balanced, or spacious
Non-Goals - Explicitly forbidden features (e.g., no_authentication, no_backend_calls)
Constraints - Technical requirements (Tailwind CSS only, flat structure, etc.)

This creates a design contract the AI must follow. The AI cannot generate code that violates the intent without explicit permission.

Intent Classification System

Before any file operation, the AI must classify your request's alignment with UI Intent. Three classifications exist:

ALIGNED (Green Badge)

The request matches UI Intent perfectly. Example:

Intent: Dashboard for analysts
Request: "Add a revenue chart"
Classification: ALIGNED (charts are appropriate for dashboards)

The AI proceeds immediately with file operations. No warnings, no blocks.

PARTIALLY_ALIGNED (Amber Badge)

The request needs minor adaptations but doesn't conflict with core intent. Example:

Intent: Professional tone, balanced density
Request: "Make the spacing tighter"
Classification: PARTIALLY_ALIGNED (visual_refinements change type)

The AI adapts the request and explains modifications. Allowed change types include:

visual_refinements (spacing, colors, borders)
layout_adjustments (grid changes, alignment)
copy_changes (text updates)
component_styling (button styles, hover states)

Disallowed change types requiring intent update:

new_capabilities (features outside product scope)
backend_logic (API calls, authentication)
product_type_change (dashboard → landing page)

CONFLICTING (Red Badge)

The request directly violates UI Intent. Example:

Intent: Product type = landing_page, Non-goal = no_authentication
Request: "Add a user login page"
Classification: CONFLICTING (authentication is forbidden)

The AI blocks file operations and explains the conflict. You have two options:

Adapt the request to align with intent (AI suggests alternatives)
Update the intent explicitly to allow the feature

Intent Update Process

When you approve an intent update, the AI uses the update_ui_intent tool:

{
  "tool_name": "update_ui_intent",
  "arguments": {
    "field": "non_goals",
    "new_value": ["no_backend_calls"],
    "reason": "User explicitly requested authentication features. Removed no_authentication to allow user login system."
  }
}

Every intent change requires a reason. This creates an audit trail showing why your app's design evolved. All intent versions are stored in the database with timestamps and attribution.

Intent Status Badge

The UI builder header shows an intent status badge:

🟢 "Intent: Governed" - All requests aligned or adapted successfully
🟠 "Intent: Conflict Detected" - Latest request conflicts with intent

Hover the badge to see a tooltip explaining UI Intent governance. The badge updates in real-time as the AI classifies requests.

Why UI Intent Matters

Without UI Intent:

AI generates inconsistent UIs across conversations
Same prompt produces different results
Product type confusion (landing pages get dashboards features)
Feature drift (authentication appears when not needed)

With UI Intent:

Deterministic output (same intent → same quality)
Product-type-appropriate designs
Explicit feature boundaries
Transparent design evolution with audit trail

Intent Viewer and Debugger

The Intent Viewer shows your app's current UI Intent specification and evolution history.

Accessing the Intent Viewer

Click the "Intent Debugger" in the UI builder interface (on mobile it's a tab next to Preview/Chat). The viewer shows:

Current Intent Section

Displays the active UI Intent as formatted JSON:

{
  "product": {
    "type": "dashboard",
    "primary_goal": "Sales metrics visualization",
    "success_metrics": ["Task completion speed", "Data comprehension"]
  },
  "audience": {
    "persona": "Sales analysts",
    "experience_level": "technical"
  },
  "design": {
    "tone": "professional",
    "visual_density": "balanced"
  },
  "non_goals": [
    "no_authentication",
    "no_backend_calls",
    "no_marketing_content"
  ]
}

This is read-only. You cannot edit intent directly—all changes must come from AI conversations with explicit reasoning.

Evolution Metrics Section

Shows quantitative data about intent changes:

Intent Update Count - Total number of times intent was modified
Drift Score - Calculated based on frequency and type of changes
Stability Rating - High/Medium/Low based on update patterns
Non-Goals Removed - How many restrictions were relaxed
Product Type Changes - Whether product type ever changed
Constraint Relaxations - Technical constraints that were loosened

These metrics help you understand if your app's design is stable or constantly shifting.

Version History Section

Lists all intent versions chronologically:

Version 3 - 2 hours ago
Updated by: ai
Reason: User requested authentication. Removed no_authentication to allow user login.
Changes: non_goals: ["no_authentication", "no_backend_calls"] → ["no_backend_calls"]

Version 2 - 1 day ago
Updated by: ai
Reason: User changed focus to analytics. Updated product type to dashboard.
Changes: product.type: "landing_page" → "dashboard"

Version 1 - 1 day ago
Updated by: system
Reason: Initial UI Intent created from prompt
Changes: (initial creation)

Each version shows:

Version number and timestamp
Who updated it (user, ai, or system)
Reason for the change (mandatory)
JSON diff showing what changed

Click any version to see the full intent snapshot at that point in time.

Debugging with Intent

When AI behavior seems wrong, check the Intent Viewer:

Problem: AI refuses to add a feature you want Debug: Check non_goals and constraints in Current Intent section. The feature might be explicitly forbidden.

Problem: AI keeps adding features you don't want Debug: Check if those features are blocked in non_goals. If not, update intent to forbid them.

Problem: Visual style is inconsistent Debug: Check design.tone and visual_density values. Update if they don't match your preferences.

Problem: AI generates wrong component types Debug: Check product.type. Landing pages, dashboards, and SaaS apps use different components.

Problem: Intent keeps changing unexpectedly Debug: Check Evolution Metrics for high drift score. Review Version History to see what's changing and why.

Version History System

Every time the AI generates or modifies code, UI builder creates a version snapshot. This gives you unlimited undo/redo for your entire application.

How Versions Work

Versions are automatic. After each AI response that creates or modifies files, a new version is saved containing:

All files at that point in time
Which chat message triggered the version
Timestamp of creation
Linked UI Intent version (if intent changed too)

Versions are numbered sequentially: Version 1, Version 2, Version 3, etc.

Version Selector

The version selector appears in the UI builder control bar as a dropdown button showing the current version number (e.g., "Version 5"). Click it to see the version history:

✓ Version 5 - Just now (3 files)
  Version 4 - 2 hours ago (3 files)
  Version 3 - 5 hours ago (2 files)
  Version 2 - 1 day ago (2 files)
  Version 1 - 1 day ago (1 file)

The checkmark (✓) shows which version is currently selected. Each entry displays:

Version number
Relative timestamp ("2 hours ago", "Just now")
File count in that version

Switching Versions

Click any version in the dropdown to switch to it. The UI builder immediately:

Updates the file tree to show that version's files
Updates the preview to run that version's code
Marks the selected version with a checkmark

This is instant—no reloading, no waiting. You can rapidly switch between versions to compare behavior.

Version Switching Use Cases

Undo AI Mistakes

AI added broken code in Version 5
Switch to Version 4 (working state)
Send new prompt explaining the issue
AI generates Version 6 with proper fix

Compare Implementations

Version 3: Dashboard with table layout
Version 4: Dashboard with card layout
Switch between them to compare UX
Choose which approach works better

Fork from Earlier Point

Development went wrong at Version 6
Switch to Version 3 (better state)
Continue development from there
New versions (7, 8, 9) branch from Version 3

Show Progress to Stakeholders

Start with Version 1 (basic structure)
Switch through 2, 3, 4 showing evolution
End with current version (final state)
Demonstrate rapid iteration capability

Version Persistence

Versions are stored in your database, not browser memory. This means:

Versions persist across browser sessions
Close the app and reopen later—versions are intact
Work from multiple devices—versions sync automatically
No manual saving required—everything is auto-saved

Limitations

Versions are snapshots, not diffs. Each version stores complete file contents, not just changes. This means:

Large projects with many versions consume more database space
No git-style merge capabilities between versions
Version switching replaces all files atomically

Currently, you cannot:

Delete specific versions (all versions are kept)
Name versions manually (auto-named "Version N")
Create branches or merge versions
See visual diffs between versions

These features may be added in future updates based on user feedback.

CDN Management System

The CDN system lets you add external JavaScript and CSS libraries without npm installation. This is useful for lightweight dependencies and prototyping.

Accessing CDN Settings

CDN management is available in the UI builder settings panel (look for the "CDN Links" section). The panel shows:

Currently added CDN links with name and URL
"Add Custom CDN" button for manual entry
Preset buttons for popular libraries

Adding Preset CDN Libraries

Preset options include:

Tailwind CSS v4 - Utility-first CSS framework (browser CDN)
Alpine.js - Lightweight JavaScript framework
DaisyUI - Tailwind component library
Font Awesome - Icon library

Click any preset button to add it instantly. The library becomes available in your app immediately—no reload required.

Adding Custom CDN Links

Click "Add Custom CDN" to manually add a library:

Enter library name (for your reference)
Enter CDN URL (full path including https://)
Select type: Script (<script> tag) or Stylesheet (<link> tag)
Add optional description

Example for a chart library:

Name: Chart.js
URL: https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js
Type: Script
Description: Simple JavaScript charting library

CDN vs NPM Packages

Use CDN links when:

Library has a browser-ready CDN version
You want zero configuration setup
File size is small (< 100KB)
You're prototyping and need quick testing

Use NPM packages when:

Library requires build-time processing
You need tree-shaking for smaller bundles
Library has many interdependent modules
You're building production applications

Tailwind CSS v4 Special Case

Tailwind CSS v4 has a browser CDN mode. When you add the Tailwind preset, it injects:

<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

This enables Tailwind utility classes without build configuration. The browser version scans your HTML and generates CSS on-the-fly.

Note: Browser CDN is great for prototyping but slower than build-time Tailwind. For production apps, use the NPM package version.

Removing CDN Links

Each CDN link has a remove button (trash icon). Click it to remove the library. The UI builder updates automatically—removed libraries are no longer injected.

CDN Storage

CDN links are stored per-app in the database (ui_apps.sandpack_cdn_links column). This means:

Each app has independent CDN configuration
CDN links persist across sessions
No localStorage usage—everything in database
Links sync across devices automatically

Downloading Your Project

The download feature exports your entire project as a ZIP file. This lets you run the code locally or deploy it to other platforms.

Download Button

Click the download button in the UI builder control bar (cloud icon with down arrow). The browser immediately downloads a ZIP file named after your app (e.g., my-dashboard-app.zip).

ZIP Contents

The ZIP includes:

All generated files (App.js, components, styles, etc.)
package.json with NPM dependencies
index.html as entry point
CDN links injected into HTML head

The structure is flat (no src/ directory) matching the UI builder structure.

Running Locally

After extracting the ZIP:

# Install dependencies
npm install

# Start development server (requires local bundler setup)
npm start

Note: The exported code is Sandpack-compatible but requires a bundler setup locally. For production use, you may need to:

Restructure files into src/ directory
Add build configuration (webpack, vite, etc.)
Update import paths if restructuring
Replace CDN links with NPM packages for better performance

Every user can export their projects freely.

Pro Tips

Tip 1: Use Specific Version References When asking AI to revert changes, reference version numbers:

"Switch back to the layout from Version 3"

This is clearer than "undo the last change" which can be ambiguous.

Tip 2: Describe Desired State, Not Steps Instead of: "Add a button, make it blue, then add click handler" Try: "Add a blue button that logs 'clicked' when pressed"

AI generates complete implementations rather than applying steps sequentially.

Tip 3: Check Console for Runtime Errors If preview shows blank screen, switch to Console mode. Syntax errors and runtime exceptions appear there with stack traces.

Tip 4: Use Read Operations for Context Ask AI to read files before complex updates:

"Read App.js and then add error boundaries"

This ensures AI has current context and avoids outdated assumptions.

Tip 5: Download Before Major Refactors Always download before asking AI to restructure the entire app. If the refactor fails, you can restore from the ZIP.

Common Issues and Solutions

Issue: Preview Shows Blank Screen

Cause: Runtime error preventing React render

Solution:

Switch to Console mode
Look for red error messages
Find error location in stack trace
Ask AI: "Fix the error on line X in file Y"

Issue: CDN Library Not Working

Cause: CDN script not loaded before component renders

Solution:

Check browser dev tools Network tab
Verify CDN URL loads successfully (200 status)
If 404, remove CDN link and add correct URL
Ensure library is accessed after script load (use useEffect)

Issue: NPM Package Import Fails

Cause: Package not fully installed or wrong import syntax

Solution:

Wait 10 seconds after adding package
Refresh preview manually
Check import syntax matches package documentation
Try removing and re-adding package

Issue: File Changes Not Reflected

Cause: Preview cache or React hot reload issue

Solution:

Click refresh button in control bar
If still not working, switch versions back and forth
Last resort: Ask AI to delete and recreate the file

Issue: Intent Blocks Valid Request

Cause: Non-goal too broad or product type mismatch

Solution:

Open Intent Viewer to see current intent
Identify specific constraint blocking request
Ask AI: "Update intent to allow [feature], reason: [your reasoning]"
Retry original request

Issue: AI Generates Wrong File Paths

Cause: AI assumes src/ directory structure

Solution:

Remind AI: "Use flat structure, no src/ directory"
Check filesystem in Files mode to see actual structure
If files created in wrong location, ask AI to move them

Issue: Too Many Versions Clutter History

Cause: Every AI response creates a version

Solution: Unfortunately, you cannot delete individual versions currently. This is a known limitation. Future updates may add version pruning or manual deletion.

Workaround: Focus on meaningful versions. Skip reviewing intermediate versions during rapid iteration.

Falta algo ou está errado neste guia? Fale connosco