Microcopy

Microcopy

Concept of the skill

Microcopy is the functional text inside a working interface: the button label a user reads before clicking, the empty state they meet when they first arrive, the error message that appears when something fails, the tooltip that answers "what is this?", the toast that confirms "done." It is distinct from marketing copy (which persuades) and documentation (which teaches at length) — microcopy's job is to make the interface operable, telling the user what just happened, what will happen if they act, and what to do next, in as few specific words as possible. The discipline is not free-form writing; each interface surface carries a fixed shape the words must fill — verb-first action labels, acknowledge → explain → guide empty states, consequence-first confirmations, What → Why → What-to-do errors, progressive loading language keyed to elapsed time, blur/fix validation. This skill exists because functional UI text is structurally unowned in most products: copywriters own the marketing surfaces, tech writers own the docs, naming conventions own code identifiers, but nobody owns the words inside the running interface — so the placeholder text written during implementation ("Submit", "Error occurred", "No data") ships and stays forever. The skill replaces that accidental quality with surface-specific patterns and a verification checklist, so the words a user actually reads are short, specific, actionable, and correct for the surface they appear on.

Coverage

Functional UI text patterns across all interactive surfaces:

• Button labels — verb-first, specific action, max 3 words; never generic ("Submit", "OK", "Yes", "Continue")
• Empty states — three-part structure: acknowledge → explain → guide, with one primary action
• Tooltips — one sentence, no terminal period, answers "what is this?"
• Confirmation dialogs — state the consequence first, name the action in the button, always provide an escape
• Placeholder text — example format not instruction; never the only label for a field
• Loading and progress messages — progressive disclosure: nothing → spinner → skeleton → message → reassurance, by elapsed time
• Error / success / warning messages — three-part What → Why → What-to-do structure with blame-free framing
• Inline form-validation messages — appear on blur, disappear on fix, specific not generic
• Toast / snackbar messages — action plus context, undo for reversible actions, auto-dismiss after 5 seconds, max 2 lines
• Permission request copy — explain why before asking
• Onboarding step copy — one action per step, progressive disclosure, time-honest

Philosophy of the skill

Microcopy is the most-read, least-reviewed text in any application. A user may never read the docs, skip the onboarding, and ignore the marketing — but they will read the button label before clicking it. They will read the error message when something fails. They will read the empty state when they first arrive. These micro-moments determine whether the user feels confident or confused, and they compound across every interaction.

The failure mode is predictable: developers write placeholder microcopy during implementation ("Click here", "Error occurred", "No data"), it ships because nobody reviews it, and it stays forever. Agents make it worse — they default to verbose, hedged, generic text ("An error has occurred while processing your request. Please try again later.") when users need short, specific, actionable text ("Payment failed — check your card number.").

This skill exists because microcopy quality is structurally unowned in most projects. Marketing copy has a copywriter. Documentation has a tech writer. Naming has a convention. But nobody owns the words inside the working interface — the button that says "Submit" when it should say "Save Changes", the empty state that says "No items" when it should say "No orders yet — connect your storefront to start syncing." The cost of that gap is paid one click at a time.

Scope boundary: microcopy writes FUNCTIONAL UI text — button labels, error messages, empty states, tooltips, confirmation dialogs. It does NOT cover marketing copy or content-strategy decisions; those belong to dedicated copywriting and content-strategy skills.

---

1. Button Labels

Buttons are the primary action interface. Every button label is a micro-contract: it promises what will happen when clicked.

Rules:

1. Verb-first: "Save Changes", "Connect Storefront", "Export CSV" — not "Changes", "Storefront", "CSV"
2. Specific action: "Delete Order" not "Delete", "Send Invitation" not "Send"
3. Max 3 words for primary actions: "Save", "Save Changes", "Save and Close"
4. Match the consequence: if clicking deletes data, the button says "Delete" not "OK". If it sends an email, it says "Send Email" not "Confirm"
5. Avoid generic labels: "Submit", "OK", "Yes", "Continue" are almost always wrong — name the actual action
6. Cancel is always available: destructive dialogs need both the action ("Delete Order") and the escape ("Cancel")

Button label patterns by context:

Context	Bad	Good
Save form	Submit	Save Changes
Delete item	OK	Delete Order
Connect platform	Continue	Connect Storefront
Export data	Download	Export as CSV
Confirm send	Yes	Send Invitation
Dismiss dialog	Close	Cancel

---

2. Empty States

Empty states are the first impression for every new feature. They must acknowledge, explain, and guide.

Three-part structure:

1. Acknowledge — "No orders yet" — confirm the user is in the right place and the emptiness is expected
2. Explain — "Orders will appear here once your storefront syncs" — tell them why it's empty and when it won't be
3. Guide — "Connect Storefront" (button) — give them the action that fills the empty state

Rules:

• Never just "No data" or "Nothing to show" — this is a dead end
• Use "yet" to imply future content: "No orders yet" vs "No orders"
• Include one primary action button that resolves the empty state
• For filtered empty states: "No orders match your filters" + "Clear filters" button
• For error empty states: "Could not load orders" + "Try again" button + brief explanation

Common empty-state patterns:

Surface	Message	Action
Orders table (new user)	No orders yet	Connect Storefront
Orders table (filtered)	No orders match these filters	Clear filters
Dashboard (no data)	Connect a storefront to see your profits	Get Started
Product list (empty)	No products synced yet	Sync Products

---

3. Tooltips

Tooltips answer one question: "What is this?"

Rules:

• One sentence maximum, no period at the end
• Answer "what is this?" or "why would I use this?" — not "how does this work?"
• Never repeat the label the tooltip is attached to
• No links in tooltips (they disappear on mouseout)
• Use sentence case for the first word only
• Appear on hover after 300ms delay, dismiss on mouseout

Examples:

• Production-cost field: "Cost of goods sold, including production and shipping to your fulfillment center"
• Confidence badge: "How complete the profit calculation is for this order"
• Sync status icon: "Last synced 5 minutes ago from your storefront"

---

4. Confirmation Dialogs

Confirmation dialogs exist for one reason: preventing irreversible mistakes.

Rules:

1. State the consequence first: "This will permanently delete 3 orders and their associated profit data."
2. Name the action in the button: "Delete 3 Orders" not "Confirm" or "OK"
3. Provide the escape: "Cancel" button, always present
4. No double negatives: "Don't cancel" is never the right label
5. Include the count: "Delete 3 orders" not "Delete selected orders"
6. Distinguish destructive from reversible: red button + explicit "permanently" for destructive; normal button for reversible

---

5. Error Messages

Error messages are the most important microcopy in the application. When something fails, the user needs clarity, not apology.

Three-part structure:

1. What happened: "Payment failed" — state the failure clearly
2. Why: "Your card was declined" — give the specific reason if known
3. What to do: "Check your card details or try a different payment method" — actionable next step

Rules:

• Never "An error occurred" — say what errored
• Never "Please try again later" — say what to try or when later is
• Blame-free framing: "We couldn't sync your orders" not "You have a sync error"
• Include error codes only in technical contexts, never in user-facing messages
• For transient errors: "Sync paused — retrying automatically" with a progress indicator

The general blame-free / What → Why → What-to-do framing is the linguistic rule (see linguistics); microcopy applies it specifically to in-product error toasts, banners, and inline messages.

---

6. Loading and Progress

Users tolerate waiting when they understand what's happening.

Progressive disclosure by elapsed time:

• 0 – 300 ms: show nothing (the action feels instant)
• 300 ms – 2 s: show spinner or skeleton (brief acknowledgment)
• 2 – 10 s: show message ("Syncing your orders from your storefront…")
• 10 s+: show progress ("Syncing orders… 47 of 312")
• 30 s+: show reassurance ("This may take a few minutes for large stores. You can leave this page.")

---

7. Inline Validation Messages

Validation messages appear at the field level, not the form level.

Rules:

• Appear on blur (not on keystroke — that's hostile)
• Disappear as soon as the user fixes the input
• Specific, not generic: "Email must include @" not "Invalid input"
• Placed below the field, not in an alert box
• Red text + icon for errors, green for success (with non-color indicator for accessibility)
• Never use exclamation marks in validation messages

---

8. Toast / Snackbar Messages

Toasts confirm completed actions. They are the UI's "done" signal.

Rules:

• Action + context: "Order #1234 deleted" not "Item deleted"
• Include undo for reversible actions: "Order archived. Undo"
• Auto-dismiss after 5 seconds (configurable for actions with undo)
• Max 2 lines of text
• Stack from bottom, newest on top
• Never use toasts for errors — errors need persistent, in-context display

---

Verification

After writing or reviewing UI text, verify:

• Button labels are verb-first and name the actual action (no "Submit", "OK", "Yes", "Continue" alone)
• Empty states acknowledge → explain → guide, with a real next-step button
• Tooltips are one sentence, no terminal period, and answer "what is this?"
• Confirmation dialogs state the consequence first and name the action in the button (with a Cancel escape)
• Placeholder text is an example format, not the only label
• Loading messages follow progressive disclosure by elapsed time, not a single state
• Error messages follow What → Why → What-to-do, blame-free, with a specific action
• Inline validation appears on blur and disappears on fix; messages are specific, not generic
• Toasts include action + context and an undo path for reversible actions
• Functional UI text stays inside the interface — does not drift into marketing or documentation territory

Do NOT Use When

Instead, use	Why
linguistics	The user wants the underlying linguistic rule (morphology, polysemy, register), not the specific UI-text pattern. Linguistics owns the why; microcopy owns the what to write.
documentation	Writing or restructuring long-form prose for guides, tutorials, reference docs, or help-center articles. Documentation owns doc architecture and prose; microcopy owns in-product UI text.
a11y	Auditing UI text for screen-reader announcement, aria-live behavior, or color-contrast compliance. A11y owns the accessibility contracts; microcopy owns the words.
naming-conventions	Deciding the casing format for an artifact kind (kebab vs camel vs snake). Naming-conventions is for code identifiers, not user-facing UI strings.
intent-recognition	Disambiguating a user's intent from an ambiguous prompt. Intent-recognition is upstream of any UI; microcopy is the words the UI uses to respond.
(a copywriting skill)	Marketing headlines, pricing copy, landing-page persuasion, brand-voice work. Copywriting owns persuasive product surfaces; microcopy owns functional in-product text.
(a content-strategy skill)	Page structure, funnel strategy, or what content belongs on each page. Content strategy is upstream of microcopy.
interaction-feedback	When and how feedback states appear (timing, placement, persistence, recovery). Interaction-feedback owns the staging; microcopy owns the words inside the staged element.