Instruction file imported from ramxcodes/r3-deck (.cursor/rules/ux-copy.mdc). Copyright stays with the author.

UX copy clarity

Improve unclear interface text so the product is easier to understand and use.

Before writing copy

Know the audience (first-time vs technical), their state (stressed on error, calm on success), and the one action you want next.

Error messages

• Say what went wrong in plain language.
• Say how to fix it.
• Do not blame the user.
• Add an example when format matters.

// bad
"Project limit reached (1)."
"Error 403: Forbidden"
"Invalid input"

// good
"Uh-oh — you're on the Free plan, so you can have only 1 active project at a time. Please upgrade to Pro."
"You don't have permission to view this page. Ask an admin for access."
"Email needs an @ — try name@example.com"

Plan/quota FORBIDDEN toasts are info (toastApiError), not red errors.

Buttons and CTAs

Verb + noun: “Create project”, “Save changes”, “Delete forever”. Avoid “OK”, “Submit”, “Click here”.

Empty states

Explain why it’s empty and offer the next action: “No projects yet. Create one to get started.”

Confirmations

Name the thing and the consequence: “Delete ‘Architecture overview’? This can’t be undone.”

Principles

Be specific, concise, active, human, helpful, and consistent with the same terms everywhere.

Never

Jargon without explanation, vague “something went wrong”, passive blame, humor on errors, or varying the same concept’s name.