Skip to content

Commit a724a84

Browse files
LineIndentLineIndent
authored
add best practice docs (#1581)
1 parent 35c35cb commit a724a84

File tree

2 files changed

+176
-0
lines changed

2 files changed

+176
-0
lines changed

‎docs/ai_builder/overview/best_practices.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Reflex Build: Best Practices
2+
3+
> A comprehensive guide to working effectively with AI Builder. This guide outlines how to get the most reliable and efficient results when working with the AI Builder inside Reflex Build. The key to success is clarity, structure, and iteration.
4+
5+
---
6+
7+
## Core Workflow
8+
9+
### Foundation: Planning Before You Build
10+
11+
Before jumping into the AI Builder, take time to plan your approach. Good preparation leads to better results and fewer iterations.
12+
13+
- **Define your core purpose and users** — Write a 2-3 sentence app description and identify your target users and their needs.
14+
- **Prioritize 3-5 key features** — Focus on the most important functionality first, then expand from there.
15+
- **Gather visual references** — Collect screenshots, wireframes, or sketches of layouts you want to emulate.
16+
- **Structure your data** — List what information each page needs to display and how users will interact with it.
17+
- **Start with your most important page** — Usually your main dashboard, home screen, or primary workflow. Get this right first.
18+
19+
### Auto-Generate Prompts from App Specs
20+
21+
To save time and get higher-quality prompts, you can feed your full app spec into **Chat Mode** and ask it to break the spec into structured, build-ready prompts.
22+
23+
Chat Mode can translate your vision into:
24+
25+
- Layout instructions
26+
- UI component definitions
27+
- Data model requirements
28+
- Styling preferences
29+
- Follow-up test plans
30+
31+
Once generated, copy each prompt into the AI Builder to execute them in sequence.
32+
33+
**Example workflow:**
34+
35+
1. Switch to Chat Mode and paste your full app specification
36+
2. Ask: *"Break this into a series of buildable prompts I can feed into the Agent Mode."*
37+
3. Copy each generated prompt into Agent Mode one by one
38+
4. Build iteratively using the structured prompts
39+
40+
### Working with Text Specifications
41+
42+
If you have a structured app specification, don't paste the entire document into the builder at once. Break it down into logical sections and feed them in sequence.
43+
44+
**Pro tip:** Use **Chat Mode** to help prepare prompts:
45+
46+
- Paste your full app spec and ask: *"Break this into buildable prompts I can feed into the builder."*
47+
- Or ask: *"Write one prompt per feature/page to build this app."*
48+
49+
This hybrid approach — planning in **Chat Mode**, then building in **Agent Mode** — lets you move faster and build smarter.
50+
51+
### Writing Clear, Task-Oriented Prompts
52+
53+
The AI performs best when it receives **specific, outcome-driven instructions**. Avoid vague, broad prompts.
54+
55+
❌ **Bad:**
56+
> "Build me an admin dashboard."
57+
58+
✅ **Good:**
59+
> "Create a 2-column layout with a sidebar for navigation and a top navbar."
60+
61+
Whenever possible, split large tasks into smaller steps:
62+
63+
- Define the layout first (columns, rows, sidebar)
64+
- Add UI components (buttons, inputs, modals)
65+
- Handle data models and states later
66+
- Use follow-ups to style and polish
67+
68+
Use precise styling language, for example:
69+
> "Add medium spacing between grid items and use large rounded corners on cards"
70+
71+
Avoid subjective terms like "nice," "modern," or "clean." Treat your prompt as interface documentation for the builder.
72+
73+
### Working with Images and Visual References
74+
75+
You can drop in screenshots of websites, dashboards, apps, or even hand-drawn wireframes. The builder will extract layout, design, and functionality ideas from these images.
76+
77+
**Tips for images:**
78+
79+
- Clear screenshots work best
80+
- Include any elements you want: forms, tables, nav, charts
81+
- You can annotate them with arrows, notes, or labels
82+
83+
**Get UI/UX feedback using Chat Mode:**
84+
85+
- Upload a screenshot and ask: *"What are 5 things I could do to improve the UI/UX of this?"*
86+
- Follow up with: *"Implement items 1, 2, and 4 in the builder."*
87+
- Or request specific improvements: *"Make this more minimal and mobile-first."*
88+
89+
---
90+
91+
## Optimizing Your Workflow
92+
93+
### Building Iteratively
94+
95+
Trying to generate your full app in a single prompt almost never works well. Instead, approach your build in clear stages:
96+
97+
1. **Layout** — Grid, Flex, responsive columns/rows
98+
2. **Components** — Tables, buttons, modals, charts, etc.
99+
3. **State** — Bindings, stores, mock data
100+
4. **Refinement** — Tweaks, visual polish, edge case handling
101+
102+
At each stage, give feedback and iterate. If the AI builder makes something close, you can say:
103+
104+
> "Reuse this structure but remove the modal and make the sidebar collapsible."
105+
106+
**Reuse and reference earlier outputs:**
107+
108+
- *"Use the same button style from the home page here."*
109+
- *"Repeat the card layout from the dashboard section."*
110+
- *"Match the data table structure from the 'Users' tab."*
111+
112+
### Improving UI/UX
113+
114+
To improve your design, ask the builder for more polished layouts, better structure, or more modern styles.
115+
116+
**Examples:**
117+
118+
- *"Make this more minimal."*
119+
- *"Improve visual hierarchy."*
120+
- *"This page feels dense. Add more spacing and reduce visual clutter."*
121+
- *"Make this more mobile-first."*
122+
123+
**Suggested workflow:**
124+
125+
1. In Chat Mode, upload an image or describe the layout.
126+
2. Ask: *"Tell me 5 things that would improve the UI/UX of this page."*
127+
3. Review the suggestions and decide which ones you want to apply.
128+
4. Switch to Agent Mode and implement: *"Improve visual hierarchy by increasing heading sizes and adding more spacing between sections."*
129+
130+
### Using Knowledge to Guide the Build
131+
132+
The **Knowledge** panel lets you provide long-form references that influence how the agent builds your app. Add design systems, style guides, brand guidelines, or architecture rules.
133+
134+
Once added, the builder will try to honor these rules throughout the session, ensuring consistency without repeating instructions.
135+
136+
**Try combining Knowledge with Chat Mode:**
137+
138+
- *"Use the style guide in Knowledge to improve this page."*
139+
- *"Is the current layout aligned with our design system in Knowledge?"*
140+
141+
### Local Development Integration
142+
143+
We have an MCP server available for enterprise customers to connect local AI development tools such as Claude Desktop, Windsurf, or Codex.
144+
145+
This enables a hybrid workflow: generate your app and make major changes in the App Builder, then move to local development for detailed refinements and custom functionality.
146+
147+
> **🏢 Enterprise Feature:** The Reflex MCP integration is currently only available for enterprise customers. [Book a demo](https://reflex.dev/pricing/) to discuss access.
148+
149+
#### Quick Setup
150+
151+
**Prerequisites:**
152+
153+
- MCP-compatible AI tool (Claude Desktop, Windsurf, Codex)
154+
- Valid Reflex account for OAuth authentication
155+
- Internet connection to the hosted MCP server
156+
157+
**Benefits:**
158+
159+
- **Seamless handoff** — Move between web builder and local development
160+
- **AI-powered local development** — Use your preferred AI tools with Reflex projects
161+
- **No local installation** — Hosted MCP server requires no additional Python packages
162+
- **Secure authentication** — OAuth 2.1 integration with your Reflex account
163+
164+
For complete setup instructions for Claude Desktop, Windsurf, Codex, and other MCP clients, visit our [MCP integration](https://reflex.dev/docs/ai-builder/integrations/mcp-installation/) documentation.
165+
166+
---
167+
168+
## Key Takeaways
169+
170+
- **Plan before you build**. A few minutes of preparation saves hours of iteration.
171+
- **Think modularly**. Focus on atomic parts before the full system.
172+
- **Write like a designer-developer**. Clear, structural, and functional language wins.
173+
- **Iterate continuously**. Let each prompt get you 80% there, then refine.
174+
175+
With these techniques, the AI Builder becomes a reliable extension of your creative and technical intent.

‎pcweb/components/docpage/sidebar/sidebar_items/ai.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ def get_sidebar_items_ai_builder_overview():
1111
"Overview",
1212
children=[
1313
ai_builder.overview.what_is_reflex_build,
14+
ai_builder.overview.best_practices,
1415
# ai_builder.overview.use_cases,
1516
# ai_builder.overview.quickstart,
1617
# ai_builder.overview.frequently_asked_questions,

0 commit comments

Comments
 (0)