in beta
Projects gives you a way to create and edit applications with your real code using AI and visual tools. Follow these best practices to get the most out of Projects.
To get the most out of AI-powered editing in Projects, consider some of the best practices below:
AI needs example code to work effectively. Your connected repository must contain working examples of your components. Without real-life code for the AI to analyze, it can't understand how your components should be used.
If you don't have these examples in the repository you are working from, you can add additional repositories to projects.
The quality and comprehensiveness of your example code directly impact the AI's ability to generate useful results.
Treat your interaction with Builder's AI as a conversation: give feedback, point out what to change, and continue refining until you reach the desired result.
- Give specific feedback: the first output doesn't have to be final.
- Work iteratively: each response is an opportunity to steer closer to your goal.
Providing clear, contextual feedback helps the AI learn your intent and improves the outcome.
AI understands your prompts better when you include images. Use screenshots to show issues that need fixing or provide design inspiration for new features.
In the video below, both a screenshot and PDF file are used as inspiration for creating a new feature.
The more context you provide, the better the AI can help you create and iterate on your project. Provide context content by either of these options:
- Paste files into the Projects prompt.
- Click the plus icon and select your files.
Supported file types to upload include:
| Extension | File type name |
|---|---|
| CSV (comma separate values) file |
| Microsoft Word file |
| EPUB file |
| HTML file |
| JSON file |
| OpenDocument Text file |
| PDF file under 100 pages |
| rich text file |
| text file |
| Microsoft Excel file |
You can upload up to 20 files per chat, with a maximum size of 30 MB per file. For files other than PDFs, the AI can only use the text content, not the images.
Developers can also add a .builderrules or AGENTS.md file to the repository with specific instructions. For more detail, see the Add custom instructions section of Connect GitHub to Projects. For all available context types in Projects, see Add context to Projects.
When prompting the AI, provide clear instructions with specific logic and explicit actions to avoid vague requests that produce unexpected results.
The AI might infer behavior that doesn't match your intent; for example, using nonexistent data or adding unrelated elements.
- Define your preferred logic: include relevant logic or conditions the AI should follow.
- State the action clearly: use explicit instructions.
Examples of clearly stated actions:
- Add a blue primary button labeled 'Login' in the top-right corner of the header that links to /login.
- Update the product card to show a red 'New' badge in the top-left corner if the product tag equals 'new'
| ❌ Don't | ✅ Do |
|---|---|
"Add logic for content length." | "Add logic in the article card to display the number of words, and show it next to the publish date." |
"Fix this section." | "In the product grid, fix the layout issue where items overflow the container on mobile screens. Use CSS Flexbox and ensure items wrap properly." |
// ❌ Don't: Give me an "about us" page.
// ✅ DO:
Page: About
Title: Meet the team behind [Product/Company Name]
Hero: Full-width team photo with soft gradient overlay and centered headline
H1 text: About Us — We Build High-Impact Software Teams
Description: We are a distributed team of designers, engineers, and product thinkers
building [product focus]. Currently hiring for frontend, backend, and product roles.
CTA: View Open Positions
Section 1: Our Mission
- Icon + headline grid (3 items)
- Each block includes: icon, short headline, and 1-sentence blurb
Section 2: Team Photos
- Masonry layout of candid team photos
- Caption text: team retreats, pair sessions, etc.
Footer: Standard site footer with nav linksUse mix-and-match prompt patterns for faster, more consistent results:
| Layout type | Prompt to use |
|---|---|
Hero Section | "Full-width hero with product tagline, large headline, supporting text, primary CTA button, and feature image to right." |
Feature Grid | "Three-card layout with icons, feature titles, and 2-line descriptions. Cards should lift slightly on hover." |
Pricing Table | "Responsive layout with three pricing plans. Highlight the most popular plan, add toggle switch for monthly/annual pricing, and list included features." |
Testimonial | "Carousel with user avatars, quotes, and a 5-star rating component. Fades in with autoplay and manual navigation." |
Describe your interface using specific component terminology and standard section names. This helps the AI understand your project's structure and intent.
Use specific UI components and section names in your prompts:
- Cards: for content grouping.
- Badges: for status indicators.
- Toasts: for notifications.
- Toggles: for state switching.
- Form fields: for data input.
- Modals: for focused interactions.
- Hero, Feature Grid, Testimonials, Pricing: for standard page sections.
Example prompts:
- "Add a toast when the user clicks save."
- "Add a Feature Grid with three cards below the Hero."
- "Open a modal with a CTA button when 'Subscribe' is clicked."
Define your brand guidelines and design systems once and reuse them consistently using Custom Instructions.
Include guidelines for:
- Primary and secondary colors
- Typography scale and font families
- Border radius and spacing standards
- Animation and interaction styles
- Voice and tone
Example brand guideline prompts:
| Category | Prompt |
|---|---|
Typography | "Heading: 48px bold, Subhead: 24px medium, Body: 16px regular. Limit to 2 font families to maintain hierarchy." |
Layout systems | "Use a 12-column responsive grid with 32px gaps. Apply consistent vertical rhythm with 64px section spacing." |
Spacing (8-point grid) | "The layout uses 8pt spacing throughout: 16px padding in cards, 32px between sections, and 64px header height." |
Colors | "Soft dark theme with white content cards and blue accent highlights." |
Never use placeholder texts like "lorem ipsum." AI designs better with well-structured and original copy.
This approach helps the AI understand context and generate more appropriate layouts and interactions.
Example prompt:
Add a hero with headline: "Design Faster with Builder Projects"
Subtext: "Turn ideas into UI in minutes"
CTA: "Try for free"Don't ask AI to build entire applications at once—work section by section for better results.
| ❌ One prompt | ✅ Incremental building |
|---|---|
Build me a complete e-commerce website |
|
Define the UI and get the design right before adding functionality. Visual changes become more difficult once you have multiple pages and complex logic.
Always prioritize:
- Visual design and layout.
- User experience and interactions.
- Functionality and business logic.
Push the code to the connected repository. This allows you to roll back changes if needed and track your progress.
Select specific sections, layers, or elements before prompting for more targeted results. The Design mode makes prompts more powerful by providing clear context about what should change.
For best results, use Auto Layout throughout your Figma design.
Auto layout helps the AI understand structure, spacing, and intent, resulting in cleaner code and fewer fixes later.
Apply Auto Layout to the layers in your Figma file as much as possible.
Projects is a powerful tool that can solve several coding and design challenges you may encounter. However, Projects does best with the following scenarios.
Create interfaces based on text prompts with Projects. The more detailed and clear your prompts, the better output you will have.
In the video below, a text prompt asks Projects to add a table to the bottom of the page using a specific Material UI component.
Quickly generate code without extensive configuration. Create an entire Project from prompts, Connect with GitHub, or Connect a local repository and let Projects do the rest.
In the video below, a GitHub repository is connected to Projects. The repository's application starts running in Projects and is prompted to make changes.
Here's the step-by-step workflow we recommend for using Projects effectively:
- Get your Developer to connect the repository you want to contribute to.
- Make a branch.
- Make your edits with the AI prompt or with the editing tools available in the Visual Editor.
- Send PRs (pull requests).
When the PR is merged, Projects automatically deletes the branch. This is a standard workflow item in version control. To make more edits after a merge, create a new branch for those edits and submit another PR.
If your company doesn't want to evaluate Projects with actual proprietary code, there are still options.
Option 1: use open-source example code:
- Fork an existing repository and connect it on the Projects tab. See Connecting an existing GitHub repository in the Projects document.
- Find example repositories at the bottom of the Projects tab.
Option 2: start with a low-risk internal tool code:
- If you can't connect your main production app, start with a smaller or lower-value application.
- Use the code for an internal tool that your team uses for testing purposes.
Projects uses standard development workflows that involve branches and pull requests. If you're new to version control like Git, these concepts might be new to you. This section covers what you need to know.
A branch is like creating your own personal copy of a document to work on. Just as you might make a copy of a shared Google Doc to draft changes without affecting the original, a branch lets you make changes to the website or app without changing what's live. It's your private workspace where you can experiment and make updates safely.
Create a new branch whenever you're starting a new task or feature. It's like starting with a fresh copy each time you begin a new project. This keeps your changes organized and separates you from other work happening simultaneously.
Examples of work warranting a branch might include:
- editing a nav
- iterating on a UI implementation
- changing colors so you can check for accessibility and cohesiveness in light and dark mode before merging
- anything that could be a discrete project
When you create a branch, it's like taking a snapshot. Your branch captures how everything looks at that exact moment and won't automatically get updates that teammates make to the main version.
- Your branch becomes outdated over time: like working on a copy of a document while others edit the original, the longer you work on your copy, the more different it becomes from the current version.
- Busy projects change quickly: the main codebase can change rapidly on active projects where multiple people are making updates.
- Delays make merging challenging: the longer you wait to submit your changes, the more likely your version will conflict with what others have done, making it harder to combine everything.
- Work fast and submit promptly: make your changes in small chunks and submit your PR quickly to avoid complications when merging.
When a branch is merged, Builder Projects automatically deletes the pull request's working branch; that is, your feature branch that you use to submit your PR.
A PR is like submitting changes for review. Think of it as sending a proposal that says "I've made these updates — can someone check them and approve them?"
- You're not changing the live site directly: creating a PR means suggesting changes that developers can review first.
- Reviewers can respond differently: provide feedback, request adjustments, or approve and merge your changes into the official version.
The PR process protects the live site. It prevents mistakes from immediately affecting what users see and gives technical team members a chance to ensure your changes work well with the rest of the system.
In the video below, the Send PR button is clicked after some changes are made to a Builder Project. The user is then brought to the connected GitHub repository, where they can add comments. This process does not make any updates to the code.
For more information on working with Projects and Builder's AI, visit:
- Builder Figma Plugin. Learn how to use the Builder Figma plugin to get your design into Builder.
- AI Credits. Understand Builder's AI credits and how and when they apply.
- Connect GitHub to Projects. Connect your repo to Builder so you can edit your code visually and create PRs with Builder.