Building with Precision

1. Be specific about UI components

The more precisely you describe layout and components, the less you’ll need to iterate on design. Mayson understands standard UI vocabulary, use it.

Useful component terms:

sticky header · sidebar nav · card grid · data table · modal · drawer · toast notification · badge · chip · empty state · loading skeleton · hero section · two-column layout · tab bar · accordion · command palette · dropdown menu · breadcrumb · stepper · progress bar · bottom sheet · floating action button · popover · tooltip · inline alert

Vague:

Add a navigation at the top.

Specific:

Sticky top nav with the logo on the left and two links, Dashboard and Settings, on the right. On mobile, collapse to a hamburger menu that opens a full-screen drawer.

---

2. Describe user flows, not just screens

Individual screens are easier to get right when they’re described in the context of what comes before and after them. Think in transitions, not just destinations. What does the user see first, what builds their confidence to act, and where does that action lead?

Screen-only:

Add an onboarding screen.

Flow-aware:

After sign-up, walk users through a three-step onboarding: first, they enter their display name and upload an optional avatar. Second, they pick their primary use case from three options. Third, they see a confirmation screen with a "Go to dashboard" button. Show a step indicator at the top throughout.

Flows also help the Agent wire navigation correctly between screens. Every screen should have a reason to exist, and a reason to lead to the next one.

---

3. Prompt for UI states

Every screen in a real app has multiple states: what it looks like when data is loading, when there’s nothing to show yet, and when something goes wrong. Non-technical users almost always forget to specify these, which means the Agent doesn’t generate them. The result is an app that looks polished in the happy path and broken everywhere else.

Prompt for states alongside the main screen whenever you can.

Prompt example:

The task list should have three states:

Loading: show a skeleton loader with three placeholder card rows.
Empty: show a centered illustration, the text "No tasks yet", and a "Create your first task" button.
Error: show a message, "Something went wrong. Try refreshing.", with a Retry button.

States worth specifying:

State	When it appears
Loading	Data is being fetched from the backend
Empty	The user has no data yet, or a search returns nothing
Error	A request fails or something goes wrong
Success	An action completed: form submitted, item saved, payment processed
Disabled	A button or action the user can’t take yet

A real app isn’t just a happy path. Prompt for the edges and your app will feel production-ready from day one.

---

4. Express data relationships in plain English

You never need to write a database schema. But describing how your entities relate to each other helps the Agent model the data correctly from the start, and avoids the need for structural corrections later.

Prompts that establish relationships:

Each project belongs to one user. A project can have many tasks. Each task can have one assignee (another user) and one status: To Do, In Progress, or Done.

Products belong to a shop. A shop can have many products. Each product has a name, price, description, and one or more images. Users can save products to a wishlist.

Plain language like “belongs to”, “can have many”, “linked to”, and “one or more” maps directly to database relationships. Use it freely.

For developers: This is equivalent to writing a basic ERD in prose. You can also specify uniqueness constraints (“each user can only have one active subscription”) or indexing needs (“products should be filterable by category and price range”) and the Agent will handle the implementation. For complex relational requirements, state them as numbered constraints at the end of your prompt. The Manual Builder gives you read access to the generated schema if you need to verify the structure before building further.

---

5. Prompting for auth, roles, and permissions

Auth and roles have a large footprint. They affect navigation, API guards, data visibility, and the entire session layer. State them clearly and early.

Checklist for prompting auth:

• What methods are available? (email/password, OTP, Google OAuth, magic link)
• Should users stay logged in across sessions?
• Are there multiple user roles? What can each role access?
• Is any content visible without logging in?
• Are there admin-only sections?

Example:

Auth: email and password. Users stay logged in for 30 days.

Two roles: admin and user. Admins can access a /admin panel to view all users and their activity. Regular users cannot see the admin panel at all, it should be completely hidden from their navigation.

Public pages: homepage and pricing page. Everything else requires login.

For developers: The generated auth layer uses JWT with server-side validation on all protected routes. If you need a specific auth provider (e.g., Google OAuth, GitHub OAuth, phone OTP via Twilio), name it in the prompt. For RBAC requirements beyond two roles, describe the permission matrix in plain language and the Agent will generate the appropriate middleware guards.

---

6. Prompting for mobile and responsive behavior

Mobile layout doesn’t happen automatically at the right quality without explicit guidance. If your app will be used on phones, describe the mobile experience directly, not as an afterthought.

What to specify:

• Navigation pattern on mobile (bottom tab bar, hamburger drawer, or top tab bar)
• How multi-column layouts collapse
• Components that should behave differently on small screens
• Touch-specific interactions (swipe, pull-to-refresh, long-press)
• Whether a sticky bottom CTA or floating action button should appear

Vague:

Make it responsive.

Specific:

Responsive layout:

Desktop: two-column grid with a fixed left sidebar for navigation.
Tablet: single column, sidebar collapses behind a toggle icon in the top bar.
Mobile: bottom tab navigation with four tabs (Home, Search, Saved, Profile). No sidebar. Cards stack to full-width. The primary CTA ("Create") becomes a floating action button in the bottom right.

Mobile-specific interaction patterns:

On the feed screen, users can pull to refresh. Each card can be swiped left to reveal a Delete action. Long-pressing a card opens a context menu with options: Edit, Share, and Archive.

For developers: The Agent targets standard responsive breakpoints: 640px (mobile), 768px (tablet), 1024px (desktop), 1280px (wide). You don’t need to specify these unless you have exact requirements. Stating “mobile-first” in your prompt signals that the Agent should prioritize the narrow viewport layout before scaling up. For touch interactions like swipe and long-press, name them explicitly since they require gesture handler logic that the Agent won’t add by default.

---

7. Prompting for accessibility

Accessible apps aren’t just a good practice. They’re more usable for everyone, load better on lower-end devices, and rank better in search. The Agent will produce a reasonable accessibility baseline by default, but stating your requirements explicitly raises the quality significantly.

The most impactful single-line accessibility prompt:

Ensure all text meets WCAG AA contrast (minimum 4.5:1 ratio). All interactive elements must have visible focus states.

Full accessibility prompt for higher standards:

Accessibility requirements:
- Text contrast: minimum 4.5:1 (WCAG AA) throughout.
- Focus states: all buttons, links, and inputs must show a visible focus ring when navigated by keyboard.
- Motion: all transitions and animations must respect prefers-reduced-motion. Provide a static fallback.
- Icon buttons: any button that uses only an icon must have an accessible label (aria-label).
- Form inputs: all inputs must have a visible label, not just a placeholder.
- Semantic HTML: use appropriate heading hierarchy (h1 through h3) and landmark regions.

Prompting for specific accessible interactions:

The dropdown menu should be keyboard navigable: Tab to open, arrow keys to move between options, Enter to select, Escape to close.

Error messages on form fields should be announced to screen readers, not just displayed visually.

For developers: The Agent generates semantic HTML and includes ARIA attributes when accessibility is specified. For strict compliance (WCAG 2.2 AA, Section 508, or EN 301 549), state the standard by name. The generated frontend uses focus-visible for keyboard focus styles, which means focus rings only appear for keyboard users, not mouse users. For screen reader testing, the generated components use appropriate role attributes and live regions for dynamic content updates.

---

8. Prompting for specific app types

Different app types have different structural patterns. Use these as starting frameworks and fill in the specifics.

Marketplace:

[App name] is a marketplace where [sellers] list [what] and [buyers] browse and purchase.

Seller side: create a listing with [fields], set pricing, manage orders, view earnings.
Buyer side: browse listings, filter by [attributes], view listing detail, complete a purchase, track order status.

Shared: auth for both roles, messaging between buyer and seller, review system after order completion.

SaaS dashboard / tool:

[App name] is a [category] tool for [target user]. The core action is [primary job to be done].

Dashboard: shows [key metrics] and [recent activity].
Core feature: [describe the main workflow step by step].
Settings: [what users can configure].
Subscription: [free vs paid access rules, if any].

Internal operations tool:

[App name] is an internal tool for [team/company] to [manage what]. Not customer-facing.

Users: [role A] can [actions]. [Role B] can [actions].
Core workflow: [describe the end-to-end process].
Data: [what entities are tracked and how they relate].
No public-facing pages. All routes require login.

---

9. When real-world references help vs mislead

References work best when your app’s structure closely mirrors the reference. They break down when your app shares a surface similarity but differs in fundamental ways.

Reference situation	Recommendation
Your app closely mirrors the reference in structure and flow	Use the reference, it saves significant description time
Your app borrows a specific interaction pattern	Name the pattern specifically: “…like Notion’s drag-to-reorder”
Your app shares a name or category but works differently	Describe the actual behavior instead, don’t use the reference
You want to copy a visual style, not structure	Reference the visual only: “Visually similar to Linear, dark mode, dense layout, monospace accents”

s