Voice & Tone

Marmo products should sound direct, respectful, and confident — like a knowledgeable colleague, not a bureaucracy or a chatbot. This page defines:

1. Voice (who we always are) and Tone (how we adjust by context).
2. Reusable structural formulas for every feedback surface, written in the form [part] + [part] + [part] so designers and engineers compose copy the same way each time.
3. Confirmation dialog anatomy distilled from Apple HIG, Microsoft, Polaris, Atlassian, Carbon, Material, and Nielsen heuristics.

Voice (constant)

Tone (by context)

Feedback surfaces — when to use which

Universal formulas (cheat sheet)

Every Marmo copy block resolves to one of these. Pick the surface, fill the parts.

Confirmation dialog anatomy (7 parts)

Every confirmation dialog can be broken into seven elements. Required ones must be present; optional ones unlock for higher-risk actions.

When to confirm — and when not to

Rule of thumb: If a confirmation appears more than ~3× per session for the same user, it is friction, not safety. Replace with Undo.

Apply the formulas — destructive dialog example

Title:       Delete campaign "Spring launch"?
Description: This removes 1,240 contacts and 3 scheduled emails. This action can't be undone.
Primary:     Delete campaign
Secondary:   Keep campaign
Friction:    Type the campaign name to confirm.   ← only if scope is large

Apply the formulas — non-destructive dialog example

Title:       Send invoice to Acme Inc.?
Description: They will receive a PDF and a payment link by email today.
Primary:     Send invoice
Secondary:   Keep editing

Do / Don't (button labels)

Structures — Alert (page-level)

Formula: [variant] + [title] + [body] + [optional action]

Title is sentence case. Body is one or two sentences max. If you need three, you need a Dialog.

Information / default

Title:  [What the user should know in ~4–8 words]
Body:   [Implication or context + optional "Learn more" link]
Action: [Verb + object] — e.g., "Review changes"

Success

Title: [Outcome]
Body:  [Optional detail or what happens next]

Warning

Title: [Risk or limitation in plain language]
Body:  [What to do before continuing / who is affected]

Error / destructive

Title:  [What didn't work or what can't continue]
Body:   [Specific cause if known, else bucket: network, permissions, validation, unknown]
Action: [Strongest recovery: retry, fix in settings, contact support with reference id]

Do / Don't (Alert)

Structures — Toast (transient)

Formula (success): [Verb past-tense] + [object] (+ optional Undo) Formula (error): [What failed] + [Retry link]

Single line (preferred): [Outcome or status]
Optional second line:    [Tiny detail — e.g., "We'll email you when it's done"]

• No essays. If it needs paragraphs, use Alert or Dialog.
• Reversible actions ship with Undo instead of a confirmation dialog.

Structures — Field & form errors

Formula: [What's wrong] + [How to fix] — no blame, no "Invalid".

Single field:   "Enter an email address."  /  "Use at least 8 characters."
Form-level:     Title  — "There's a problem with your submission"
                Body   — Bulleted list OR "Fix the highlighted fields below."

• Map raw API errors to one user-facing bucket if codes would confuse: "We couldn't verify that. Try again or contact support."
• Pick one form-summary pattern per product and keep it.

Structures — Empty state

Formula: [What's missing] + [Why it matters] + [First action]

Heading:     [Plain noun phrase — "No campaigns yet"]
Description: [Why this matters or what they unlock — 1 sentence]
Primary:     [Verb + object — "Create your first campaign"]
Secondary:   [Optional learn-more link]

Structures — Permission denied

Formula: [What's blocked] + [Who can grant access] + [How to request]

Title: You don't have access to this report.
Body:  Workspace owners can grant the "Reports — view" permission.
Action: Request access  /  Contact <Owner name>

Accessibility (mandatory for every dialog)

• role="alertdialog", aria-labelledby (title), aria-describedby (description).
• Default focus = safe option (secondary button) for destructive dialogs.
• Tab traps focus inside the dialog. Escape closes. Enter activates focused button.
• Icon plus label — never color alone — to signal severity.
• Toast announcements use role="status" (success/info) or role="alert" (error).

Numbers, dates, and names

• Use the same date/number format as the rest of the app (locale-aware when shipped).
• When citing a record, prefer name + id in secondary text if support needs the id: Campaign "Spring launch" (id: 48291) in description or support copy, not in the title.

Relationship to components

Implementation lives in @marmoui/ui (Alert, Dialog, Field, Toaster, EmptyState, etc.). This page governs words and structure inside those shells. For composition patterns, see Patterns and component MDX for each primitive.

Maintenance

• When you add a new feedback mechanism (e.g., banner, inline banner), extend this page with a structure block (formula + parts table + do/don't) and update the "when to use" table.
• Product marketing or legal review may add layers — link out instead of duplicating full compliance copy here.
• Sources for current structures: Apple HIG (alerts), Microsoft Writing Style Guide (4-part anatomy), Shopify Polaris (banners + buttons), Atlassian Design System (modal patterns), IBM Carbon (notifications), Google Material (dialogs + snackbars), Nielsen Norman heuristic #9 (error messages).