Core User Guide - Instruct UI

Reading Time: 20-25 minutes Goal: Master essential workflows for daily productive use

Understanding Your Workspace

Welcome to the Instruct UI editor! This section helps you navigate and use the workspace effectively.

Split-View Editor

The editor uses a split-pane interface designed for simultaneous code review and live preview:

Left Pane - Chat & Code:

• Message history showing your prompts and AI responses
• Code editor with syntax highlighting
• File tree for navigation

Right Pane - Preview & Source:

• Preview Tab: Live rendering of your generated UI
• Source Code Tab: Full code view with file switching
• Toggle between tabs using the buttons at the top

Resizable Gutter: Drag the vertical divider between panes to adjust widths. This is especially useful for:

• Testing responsiveness: Make preview narrower to simulate mobile devices
• Code focus: Expand left pane when reviewing code
• Presentation mode: Expand right pane for full-screen demos

Live Preview & Interactive Testing

The preview pane is not just a static image - it's your UI running live in real-time.

What You Can Do:

• Interact with UI: Click buttons, fill forms, toggle switches
• Test navigation: Type routes in address bar (e.g., /users/123)
• Use browser controls: Back/forward buttons work
• Check responsiveness: Drag resize handle to test different widths
• View current width: Indicator shows preview width in pixels (e.g., 320px, 768px, 1920px)

Responsive Width Indicator: Pay attention to how your UI looks at common breakpoints:

• 320px - Small mobile phones
• 768px - Tablets
• 1024px - Small laptops
• 1920px - Desktop monitors

Testing Multi-Page Applications: If you generated multiple pages (e.g., login + dashboard):

1. Use the address bar in preview to navigate between pages
2. Test route parameters: /users/1, /users/2, etc.
3. Verify data flows correctly between pages
4. Test back/forward navigation

Best Practice: Generate related pages in the same conversation for seamless navigation testing.

See also: Multi-Page Application Generation for advanced workflows.

File Tree & Code Navigation

The file tree shows your project structure with hierarchical organization.

Understanding the Structure:

• Components/ - Your .razor UI components
• Models/ - C# model classes (if generated)
• Services/ - Service classes with mock implementations
• Styles/ - CSS files (or embedded in components)

Quick Navigation:

• Click any file to view its code
• Files update in real-time as AI generates code
• Syntax highlighting helps distinguish file types

When to Use:

• Before downloading, verify all expected files are present
• Finding specific components: "Where's the UserService?"
• Understanding overall project structure
• Reviewing changes after each iteration

Framework Selection

Choose which component library and CSS framework to use before generating.

Available Options:

When to Use Which:

Choose MudBlazor if:

• Building admin panels or internal tools
• Need data grids, tables, charts
• Want professional Material Design aesthetic
• Targeting enterprise users

Choose Tailwind CSS if:

• Building marketing sites or landing pages
• Want complete design control
• Have custom branding requirements
• Prefer utility-first CSS approach

Choose Bootstrap if:

• Working on existing Bootstrap projects
• Need familiar, battle-tested components
• Want traditional web design patterns
• Rapid MVP development

How to Change:

1. Select from dropdown in the Home page before generating
2. Your last choice is remembered for next generations
3. No need to mention framework in your prompts
4. Framework cannot be changed mid-conversation

Pro Tip: Stick with one framework per project for consistency. Mixing frameworks in the same codebase can create conflicts.

Credit Management Basics

Understanding how credits work helps you budget effectively and avoid surprises before you start generating.

See also: Complete Pricing Reference | Credit Optimization Strategies

Credit Cost Breakdown

Core Operations:

• 1 credit = Text-to-UI generation (regardless of files generated)
• 0.5 credits = Fix with AI (compilation OR runtime)
• +1 credit = Image/screenshot attachment (additional)

Examples:

Simple Text Generation:

• Prompt: "Create user login form"
• Cost: 1 credit

Screenshot Generation:

• Upload screenshot + prompt: "Build this dashboard"
• Cost: 2 credits (1 for image + 1 for generation)

Generation + Fix:

• Generate UI: 1 credit
• Compilation error → Fix with AI: 0.5 credits
• Total: 1.5 credits

How Credits Are Deducted

Order of Deduction:

1. Recurring credits used first (monthly allowance from your plan)
2. On-demand credits used second (purchased separately, if recurring exhausted)

Example:

• Plan: 100 recurring credits/month
• Purchased: 200 on-demand credits
• Generation costs 1 credit
• Deducted from: Recurring credits (99 remaining)
• On-demand credits remain at: 200 (untouched until recurring exhausted)

Credit Rollover (Pro/Team Plans)

Free Trial:

• 15 one-time credits
• No renewals, no rollover

Pro and Team Plans:

• Monthly recurring credits
• Unused credits roll over to next month
• Maximum rollover: 3x monthly allowance

Example:

• Plan: 100 credits/month
• Month 1: Used 60 → 40 roll over
• Month 2: Receive 100 + 40 rolled = 140 available
• Month 2: Used 50 → 90 roll over
• Month 3: Receive 100 + 90 rolled = 190 available
• Month 3: Used 200 → Balance resets to 100 (cap at 3x = 300)

Rollover Reset: If you exceed 3x your monthly allowance, credits reset to your monthly base (not zero, but the monthly allowance).

Tracking Your Usage

View Credit Balance:

• Top navigation bar shows current balance
• Updates in real-time as you generate

Detailed Usage Tracking:

1. Go to Settings → Credits → Usage
2. See table with columns:
   • Date/Time of generation
   • Conversation link
   • Your prompt/message
   • Credits consumed
3. Filter by month
4. Paginate through history

When to Check:

• Before starting large projects (budget planning)
• Weekly review of consumption patterns
• When credit balance seems lower than expected
• End of month before renewal

When to Buy On-Demand vs. Upgrade

Buy On-Demand Credits When:

• One-time large project spike
• Occasional overflow beyond monthly allowance
• Don't want long-term commitment
• Trying platform before committing to yearly

Upgrade Your Plan When:

• Consistently running out of monthly credits
• Predictable higher usage pattern
• Monthly on-demand purchases exceed plan upgrade cost
• Want credit rollover benefits (Pro/Team)

Cost Comparison Example:

Scenario: You need 250 credits/month

Option 1: Pro 100 + On-Demand 150

• Pro plan: ~$25/month (varies)
• On-demand: 150 credits = $22.50 ($15 per 100)
• Total: ~$47.50/month

Option 2: Pro 250

• Pro plan: ~$45/month (varies)
• No on-demand needed
• Total: ~$45/month
• Plus: Credits roll over (can accumulate up to 750)

Recommendation: If you consistently need more than your plan, upgrade to higher tier for better value and rollover benefits.

Credit Best Practices

1. Use Example Prompts First Test with example prompts (free) before using credits on your actual project. This helps you understand output quality.

2. Be Specific in Initial Prompts Better first-generation results = fewer iterations = fewer credits spent.

3. Use Retry Sparingly Retry costs the same as a new generation (1 credit). If first retry doesn't work, refine your prompt instead of repeatedly retrying.

4. Use Free Features

• Cloning conversations: Free
• Reverting versions: Free
• Downloading code: Free
• Viewing diff: Free

5. Leverage Rollover (Pro/Team) Don't feel pressured to "use or lose" credits. They roll over up to 3x, so you can accumulate for large projects.

6. Track Usage Monthly Review your usage patterns monthly to:

• Understand what costs credits
• Identify opportunities to optimize
• Plan future credit needs
• Decide if plan adjustment needed

Effective Prompting

The quality of your prompts directly impacts the quality of generated code. This section teaches you how to write prompts that get better results on the first try.

Text-to-UI Best Practices

Be Specific with Details

Vague prompts lead to generic results. Specific prompts generate tailored code.

❌ Vague:

Create a dashboard

✅ Specific:

Create an admin dashboard with three metric cards at the top
(total users, revenue this month, and pending orders), a data
table below showing recent transactions, and a sidebar navigation
with links to Dashboard, Users, Products, and Settings.

What makes it specific:

• Exact count: "three metric cards"
• Named metrics: "total users, revenue, pending orders"
• Clear layout: "cards at top, table below, sidebar navigation"
• Specific links: "Dashboard, Users, Products, Settings"

Specify Component Names

Mentioning specific component types helps the AI choose appropriate implementations.

Examples:

Use data grid for the user list

Add a file upload component with drag-and-drop support

Include a date picker for the start and end date fields

Why it matters: Without guidance, the AI might use a basic HTML table when you expected MudDataGrid, or a text input when you wanted a date picker.

Mention Data Context

Tell the AI about the data your UI will display or collect.

Options:

1. Mock Data (for prototypes):

Create a product listing page with mock product data.
Each product should have name, price, image, and description.

Result: AI generates sample data for immediate preview.

2. Service Connection (for real apps):

Create a user management page that connects to UserService.
The service should have methods: GetUsers(), AddUser(), DeleteUser().

Result: AI creates mock service interface you'll implement later.

3. Model Binding (for existing models):

Create a form bound to UserModel with properties:
FirstName (string), LastName (string), Email (string),
DateOfBirth (DateTime), IsActive (bool).

Result: AI generates form fields matching your model exactly.

Include Layout Requirements

Specify responsive behavior and visual structure.

Responsive Layout Examples:

Make the layout responsive: two columns on desktop, single column on mobile

Use a mobile-first design that adapts to larger screens

Center the login form vertically and horizontally on the page

Visual Structure Examples:

Use a card-based layout with rounded corners and shadows

Create a sticky header that remains visible when scrolling

Add a footer with copyright and social media links

Iterate, Don't Over-Prompt

Bad Strategy: Write a massive prompt with every detail upfront Good Strategy: Start high-level, refine with follow-ups

Example Workflow:

Prompt 1 (High-level):

Create a user profile page with avatar, name, email, and bio

Prompt 2 (Refine layout):

Make the avatar circular and larger (200px diameter)

Prompt 3 (Add functionality):

Add an edit button that opens a modal dialog with editable fields

Prompt 4 (Polish):

Add validation: email must be valid format, bio max 500 characters

Why this works:

• You see results quickly and can adjust direction
• AI understands context from previous iterations
• Easier to identify what needs changing
• Less credit waste from "almost right" generations

Screenshot-to-UI Generation

Sometimes a picture is worth a thousand words. Use screenshots when visual accuracy matters.

When to Use Screenshots vs. Text

Preparing Your Screenshots

Do:

• ✅ Crop to show only relevant UI section
• ✅ Use high-resolution images (not blurry phone photos)
• ✅ Ensure text in image is readable
• ✅ Remove sensitive data before uploading

Don't:

• ❌ Upload entire webpage (too much irrelevant content)
• ❌ Use low-quality or pixelated images
• ❌ Include browser chrome (address bar, bookmarks)
• ❌ Upload very large files (max 2 MB)

Combining Image + Text Prompts

Screenshots work best when combined with text instructions.

Example 1: Layout + Branding

[Upload screenshot of dashboard]
Use this layout but change colors to match our brand palette:
Primary: #FF6B35, Secondary: #2196F3, Background: #F5F5F5

Example 2: Structure + Functionality

[Upload screenshot]
This is a checkout page. Recreate the layout but add:
- Real-time validation on credit card field
- Loading spinner when submitting
- Success message after payment

Example 3: Design + Framework

[Upload screenshot]
Recreate this dashboard using MudBlazor components.
Replace the custom charts with MudCharts.

Real-World Scenarios

Client Design Handoff:

1. Client sends mockup: "Build exactly this"
2. Upload screenshot to Instruct UI
3. AI generates initial code (80% match)
4. Refine with text: "Adjust spacing, change fonts to Roboto"

Competitor Analysis:

1. Screenshot competitor's UI that you like
2. Generate similar layout
3. Customize: "Change colors, add our logo, modify call-to-action"

Designer Collaboration:

1. Designer shares Figma screenshot
2. Upload to Instruct UI
3. Follow up: "Match our design system tokens for spacing and colors"

Credit Cost: Screenshot + generation = 2 credits total (1 for image, 1 for generation)

See also: Figma Integration for even better design-to-code accuracy.

Iteration & Refinement

Generated code isn't always perfect on the first try. This section teaches you how to iterate effectively.

Fix with AI - Compilation Errors

When compilation fails, you'll see red error messages in the editor.

Automatic Fix Attempts: The AI automatically tries to fix compilation errors up to 2 times without you doing anything. Just wait 10-15 seconds.

Manual Fix: If errors persist after automatic attempts:

1. Click the "Fix with AI" button
2. AI analyzes error messages and affected files
3. AI generates corrected code
4. Code recompiles automatically

Credit Cost: 0.5 credit per fix attempt

Common Compilation Errors:

• Missing using statements
• Type mismatches
• Undefined methods or properties
• Syntax errors

Best Practice: If Fix with AI doesn't resolve the error after 2-3 attempts, the original prompt might need clarification. Try rephrasing your request with more specific details.

See also: Troubleshooting Compilation Errors

Fix with AI - Runtime Errors

Runtime errors occur when you interact with the preview (not during compilation).

Example Scenarios:

• Click "Delete" button → NullReferenceException
• Submit form → validation fails silently
• Page loads → exception because data is null
• Click navigation link → routing error

How to Fix:

1. Error appears in preview pane with stack trace
2. Click "Fix with AI" button on the error
3. AI receives stack trace, error message, and component context
4. AI generates fix (usually adds null checks, loading states, or error handling)
5. Code recompiles and preview refreshes

Credit Cost: 1 credit per attempt

What AI Typically Fixes:

• Adds null checks before operations
• Includes loading states for async operations
• Implements proper error handling
• Fixes event handler exceptions

Message Retry

Use retry when you want a different interpretation of the same prompt.

When to Use Retry:

• Output went in completely wrong direction
• Want different creative interpretation
• Hoping for better result with AI randomness
• Prompt was clear, AI just took wrong approach

When NOT to Use Retry:

• Need to add more details (use new prompt instead)
• Want to refine specific aspect (use follow-up prompt instead)
• Original prompt was unclear (rephrase with new prompt)

How It Works:

1. Click "Retry" button on your message
2. AI regenerates response with same prompt input
3. Previous attempt is replaced (not saved as version)
4. Different output due to AI randomness

Example Scenario:

Your Prompt:

Create a modern dashboard

First Generation: AI creates very minimal design with basic cards

Action: Click Retry

Second Generation: AI creates richer design with charts, graphs, and metrics

Decision Tree: Retry vs. New Prompt

Is the output completely wrong direction?
├─ Yes → Use Retry (same prompt, different interpretation)
└─ No → Need to add details?
    ├─ Yes → New Prompt (add specifics)
    └─ No → Need to fix specific issue?
        └─ Yes → New Prompt (targeted refinement)

Credit Cost: 1 credit (same as original generation)

Pro Tip: Try retry once. If second attempt also doesn't work, write a more specific prompt instead of repeatedly retrying.

See also: When to Use Retry vs. New Prompt

Version History & Revert

Every iteration in a conversation is saved as a version. You can view and revert to any previous version.

When to Use Version History:

1. Unwanted Changes

• Latest iteration broke existing functionality
• AI made changes you didn't ask for
• Want to undo last few prompts

2. Comparison

• Trying different approaches (light vs. dark theme)
• Testing alternative layouts
• Comparing performance of different component choices

3. Client Feedback

• Client says: "Actually, I liked version 3 better"
• Need to go back to earlier iteration
• Stakeholder prefers previous design

4. Design Exploration

• Want to try different direction without losing current work
• Keep stable version as backup while experimenting

How to Use:

View Version History:

1. Click "History" or version dropdown in editor
2. See list of all versions with timestamps
3. Click any version to preview it

Revert to Version:

1. Preview the version first (click "View Version")
2. Verify it's the right one
3. Click "Revert to this version"
4. Continue iterating from that point

Download Specific Version:

1. Load version in preview using "View Version" button
2. Click "Download" to export that specific version
3. Useful for backing up versions you like

Real-World Scenarios:

Scenario 1: Functionality Break

• Version 8: Working dashboard with charts
• Version 9: You ask AI to add filters → Charts break unexpectedly
• Action: Revert to version 8, rephrase filter request more carefully

Scenario 2: Client Changed Mind

• Versions 1-5: Iterating on initial dashboard design
• Version 6: Made significant changes based on feedback
• Client: "Actually, I liked version 3 better"
• Action: Revert to version 3, continue from there

Scenario 3: Exploration

• Version 5: Dashboard with light theme (works well)
• Goal: Try dark theme without losing light version
• Action: Clone conversation at version 5, then modify for dark theme in clone

Best Practices:

Preview Before Reverting: Always load and review the version in preview before reverting. Make sure you're going back to the right one.

Download Versions You Like: Before experimenting with risky changes, download the current version as backup.

Don't Revert Too Far: Reverting from version 15 to version 2 loses all progress. Consider if it's better to start a new conversation or clone at a specific version.

Use Code Diff: Before reverting, check the diff viewer to see exactly what changed between versions. This helps you decide which version to revert to.

Clone for Branching: Want to try multiple directions from one point? Clone the conversation instead of reverting back and forth.

Code Diff Viewer

See exactly what changed between code versions with side-by-side comparison.

When to Use:

1. Learning

• Understanding how prompts translate to code
• Studying AI's patterns for future prompts
• Seeing how AI implements specific features

2. Auditing

• Security review: Ensure no unsafe code was added
• Quality check: Verify AI didn't remove important logic
• Verification: Confirm AI understood your intent correctly

3. Documentation

• Understanding what changed for commit messages
• Documenting changes when integrating into your codebase
• Explaining modifications to team members

Real-World Scenarios:

Scenario 1: Fix Verification

• AI fixes compilation error
• Check diff to see what was changed
• Learn: "Oh, it added null check - I should include that in my prompts"

Scenario 2: Feature Addition

• You: "Add delete button to user table"
• AI modifies table component
• Check diff: Verify it only added delete functionality, didn't break existing code

Scenario 3: Security Audit

• AI added data access code
• Check diff: Ensure no SQL injection vulnerabilities
• Verify: Confirms AI used parameterized queries correctly

Best Practices:

Verify No Unwanted Changes: Check that AI didn't delete important logic or introduce behavior you didn't request.

Learn from Patterns:

• How does AI handle null checks?
• How does AI structure event handlers?
• What patterns does AI use for async operations?

Use these insights to write better prompts in the future.

Use for Integration: The diff shows exactly what changed, which is useful when writing commit messages or explaining changes to your team.

Export & Reuse

Once you're happy with your generated code, it's time to use it in real projects or save it for future use.

Download as ZIP

Export all generated code files to a downloadable archive.

When to Download:

• Finished iterating and ready to integrate into production
• Want backup before continuing risky experiments
• Sharing code with developers outside Instruct UI
• Delivering to client

What's Included:

• All .razor files - Your Blazor UI components
• All .cs files - C# code-behind and services
• All .css files - Styling (embedded or separate)
• Complete folder structure matching Blazor conventions

Code Ownership: ✅ You fully own all generated code. There are:

• No licensing restrictions
• No attribution requirements
• Free to use in commercial projects
• Free to modify, distribute, or sell

How to Download:

1. Click "Download" button in editor toolbar
2. ZIP file downloads to your browser's download folder
3. Extract to view your Blazor components

Integration Best Practices

When integrating into your existing Blazor project:

1. Adjust Namespaces Generated code by default uses namespace BlazorApp. Update them to match your project:

// Generated:
namespace BlazorApp

// Your project:
namespace MyApp.Components.Dashboard

2. Replace Mock Services AI generates mock service implementations. Replace with your real services:

// Generated (mock):
public class UserService {
    public List<User> GetUsers() => new List<User> { /* mock data */ };
}

// Your real service:
public class UserService {
    public async Task<List<User>> GetUsers() => await _dbContext.Users.ToListAsync();
}

3. Update Dependency Injection Register services in Program.cs:

builder.Services.AddScoped<IUserService, UserService>();

4. Review for Security Even AI-generated code needs security review:

• Verify input validation
• Ensure authentication/authorization
• Review data exposure

5. Test Thoroughly

• Unit test business logic
• Integration test with real services
• UI test user workflows
• Performance test with realistic data volumes

See also: Code Integration Workflows for detailed integration steps.

Clone Conversation

Create a copy of any conversation to use as a template or starting point for variations.

When to Clone:

1. Client Variations (Agencies/Freelancers)

• Built admin dashboard for Client A
• Clone it for Client B
• Customize colors, branding, specific features

2. Theme Exploration

• Have light theme working
• Want to try dark theme without losing light version
• Clone and modify for dark theme

3. Template Creation

• Built perfect user registration form
• Clone for future projects
• Saves credits by starting from proven base

4. Experimentation

• Want to try risky changes without losing current work
• Clone to create backup
• Experiment freely in cloned version

How to Clone:

From Conversation View:

1. Open conversation you want to clone
2. Click "Clone" button in toolbar
3. New conversation created with all code and history

From History Page:

1. Find conversation in history list
2. Click "Clone" icon on the row
3. New conversation appears in history

After Cloning:

1. Rename immediately: Click title to edit
2. Use descriptive name: "Client B Dashboard - HR Focus"
3. Make your customizations
4. Original conversation remains unchanged

Real-World Example: Agency Workflow

Base Template:

Created: "SaaS Dashboard Template"
Features: User management, analytics, settings
Frameworks: MudBlazor + Tailwind

Client A (Sales-Focused):

Clone → Rename: "Client A - Sales Dashboard"
Customize: Add sales charts, revenue metrics, lead tracking
Colors: Client A brand palette

Client B (HR-Focused):

Clone → Rename: "Client B - HR Dashboard"
Customize: Add employee directory, attendance tracking, leave management
Colors: Client B brand palette

Credit Cost:

• Cloning is free
• New generations in cloned conversation cost credits normally

Clone Community Chats

Learn from and build upon community examples.

When to Use:

• Found community example close to your requirements
• Learning how experienced users prompt for complex UIs
• Getting working base to customize for your needs
• Discovering new patterns and approaches

How It Works:

1. Browse Community or Explore page
2. Click any community chat to view details
3. Click "Clone" button
4. Conversation copied to your account
5. Customize for your needs

Best Practices:

Study the Prompts:

• Learn effective prompting patterns
• See how experienced users structure requests
• Notice how they iterate and refine
• Apply techniques to your own generations

Verify Quality:

• Not all community examples are production-ready
• Review code before using in production
• Test thoroughly in your environment
• Check for security issues

Edit Conversation Title

Organize your conversations with descriptive titles for easy retrieval.

Why It Matters:

• Conversations hard to find with generic titles
• "New Chat" doesn't tell you what's inside
• Important for managing multiple projects

When to Edit:

• Immediately after creating conversation
• When organizing by client or project
• After cloning (differentiate from original)
• For conversations you'll return to later

Best Practices:

Use Descriptive Names:

• ❌ Bad: "New Chat", "Untitled", "Chat 1"
• ✅ Good: "Client X - Admin Dashboard", "User Profile Page", "E-commerce Checkout"

Add Client Name (Freelancers/Agencies):

• "Acme Corp - Employee Directory"
• "Startup Y - Landing Page"
• "Client Z - Product Catalog"

Date Long-Term Projects:

• "Q1 2026 - Employee Portal"
• "2026 Redesign - Dashboard"
• "Jan 2026 - Marketing Site"

Include Feature for Large Projects:

• "MyApp - Authentication Module"
• "MyApp - Reporting Dashboard"
• "MyApp - User Management"

Keep It Concise:

• Titles may truncate if too long
• Aim for 30-50 characters
• Front-load important info (client/project name first)

How to Edit: Click the title in conversation view to edit inline.

Next Steps

You've now mastered the essential workflows for daily productive use of Instruct UI!

Continue Learning:

• Advanced Features Guide - Team collaboration, optimization, and power user features
• Complete Reference - Quick lookup for any feature, FAQ, pricing

Put It Into Practice:

• Generate a real UI for your current project
• Experiment with different frameworks
• Try screenshot-to-UI generation
• Create reusable templates via cloning

Join the Community:

• Browse community examples for inspiration
• Share your own creations
• Learn from experienced users' prompting patterns

Document Version: 1.0 Last Updated: 2026-01-07