Micro Copy Intelligence

Micro-Copy Intelligence

Why Microcopy Matters

Microcopy is the most underestimated layer of product design. A single word on a button can change conversion by 30%. A poorly written error message causes support tickets. A delightful empty state turns a dead-end into activation. A confusing permission request tanks opt-in rates.

Most products fail at microcopy not because the words are "wrong" but because they are written by developers in a rush, never reviewed by a writer, and never tested with users. The result: vague buttons ("Submit"), hostile errors ("Invalid input"), lifeless empty states ("No data"), and permission requests that give users no reason to say yes.

This skill gives Sumi a production-grade microcopy library — 1000+ templates across every UI component, every state, every tone, and every major industry sector. Every template is copy-paste ready, with tone variants, character counts, accessibility notes, and i18n considerations.

Core Principle: Clear > Clever

The single most important rule in UX writing: clarity beats cleverness every time. Users are not reading your interface for entertainment. They are trying to accomplish a task. Every word should reduce cognitive load, not add to it.

| Principle | Description | Example | |-----------|-------------|---------| | Clear > Clever | Plain language over puns or jargon | "Save changes" not "Commit your brilliance" | | Specific > Generic | Tell them exactly what happens | "Delete 3 photos" not "Delete items" | | Human > Robotic | Write like a helpful person, not a machine | "We couldn't find that page" not "Error 404: Resource not located" | | Short > Long | Every extra word is cognitive cost | "Saved" not "Your changes have been successfully saved" | | Active > Passive | Direct the user with active voice | "Enter your email" not "Email should be entered" | | Consistent > Creative | Same action = same word everywhere | Always "Remove" or always "Delete", never both | | Helpful > Blaming | Guide, don't accuse | "That password is too short" not "You entered an invalid password" |

Voice and Tone Framework

Voice is your product's personality — it stays constant. Tone adapts to context.

Voice Spectrum (Pick Your Position)

Formal ←————————————————→ Casual
  |                           |
  Banking, Legal,         Social, Gaming,
  Enterprise              Consumer

Serious ←————————————————→ Playful
  |                           |
  Healthcare, Finance     Entertainment,
  Security                Kids, Social

Respectful ←—————————————→ Irreverent
  |                           |
  Government, Medical     Startup, Youth
  Enterprise              Consumer

Matter-of-fact ←—————————→ Enthusiastic
  |                           |
  Utilities, Tools        E-commerce,
  Productivity            Fitness, Social

Tone Adaptation by Context

The same product shifts tone based on what the user is experiencing:

| Context | Tone Shift | Why | |---------|------------|-----| | Errors | Empathetic, calm, helpful | User is frustrated — don't add to it | | Success | Warm, affirming, brief | User accomplished something — celebrate proportionally | | Empty states | Encouraging, instructional | User sees nothing — guide them to value | | Destructive actions | Cautious, specific, clear | High stakes — no ambiguity allowed | | Onboarding | Welcoming, motivating | First impressions — build confidence | | Loading/waiting | Light, reassuring | User is stuck — ease anxiety | | Permission requests | Transparent, benefit-led | User must trust you — explain why | | Pricing/payment | Trustworthy, precise | Money is involved — no vagueness | | Legal/compliance | Plain, clear, accessible | Required info — make it readable |

Content Hierarchy in UI

Every UI moment has three layers of information. Not all three are always needed.

| Layer | Purpose | Example (File Upload) | |-------|---------|----------------------| | Primary | What to do | "Upload your photo" | | Secondary | Why or context | "This will be your profile picture" | | Tertiary | How or constraints | "JPG or PNG, max 5 MB" |

Rules:

• Primary copy is always visible
• Secondary copy appears when context is unclear
• Tertiary copy appears on hover, in helper text, or when errors occur
• Mobile: reduce to primary + tertiary (space is precious)

The Microcopy Formula

For any UI element, apply this structure:

[Action Verb] + [Object] + [Benefit/Context]

Examples:

• "Save changes" = action + object
• "Upload photo to complete your profile" = action + object + benefit
• "Delete this project permanently" = action + object + context
• "Invite teammates to collaborate" = action + object + benefit

When to add benefit/context:

• The action is unfamiliar (onboarding)
• The action is irreversible (destructive)
• The action requires trust (permissions, payments)
• The action has a non-obvious outcome

Readability Scoring for UI

Target readability for UI text:

| Component | Flesch-Kincaid Grade | Max Words | Max Characters | |-----------|---------------------|-----------|----------------| | Button label | Grade 3-5 | 1-4 | 25 | | Tooltip | Grade 5-7 | 5-15 | 80 | | Error headline | Grade 4-6 | 3-8 | 50 | | Error body | Grade 5-7 | 10-25 | 150 | | Empty state headline | Grade 4-6 | 3-8 | 50 | | Empty state body | Grade 5-8 | 10-30 | 180 | | Toast message | Grade 4-6 | 3-10 | 60 | | Notification title | Grade 4-6 | 3-10 | 65 | | Notification body | Grade 5-7 | 10-25 | 150 | | Onboarding headline | Grade 3-5 | 3-8 | 50 | | Onboarding body | Grade 5-7 | 15-40 | 250 | | Helper text | Grade 5-7 | 5-15 | 100 | | Confirmation dialog title | Grade 4-6 | 3-8 | 50 | | Confirmation dialog body | Grade 5-7 | 10-30 | 180 | | Permission request body | Grade 5-7 | 15-35 | 200 | | Loading message | Grade 3-5 | 2-8 | 50 |

Testing readability: Paste your copy into Hemingway Editor or use the Flesch-Kincaid formula. If a 12-year-old cannot understand it instantly, rewrite it.

Inclusive Language Checklist

Before shipping any microcopy:

• [ ] Gender-neutral: "They" not "he/she". "Spouse" not "husband/wife". "Parent" not "mother/father" (unless context-specific).
• [ ] Ability-neutral: "Select" not "Click". "View" not "See". "Enter" not "Type". Avoid "simple", "easy", "just" (what is easy for you may not be for them).
• [ ] Age-neutral: Avoid generational slang. "Download" not "Yeet this to your device".
• [ ] Culture-neutral: Avoid idioms that do not translate ("break a leg", "piece of cake"). No sports metaphors as primary copy.
• [ ] Jargon-free: "Sign in" not "Authenticate". "Save" not "Persist". "Error" not "Exception".
• [ ] No assumptions: Do not assume family structure, location, device, connection speed, or technical literacy.
• [ ] Respectful defaults: "Preferred name" not "Nickname". "Phone number (optional)" not "Mobile number (required)".
• [ ] Error messages blame the system, not the user: "We couldn't process that" not "You made an error".

i18n Considerations for Microcopy

Microcopy that works in English may break in translation. Plan ahead:

Text Expansion

| Language | Expansion vs. English | |----------|----------------------| | German | +30-35% | | French | +15-20% | | Spanish | +20-25% | | Italian | +15-20% | | Portuguese | +20-30% | | Russian | +15-20% | | Japanese | -10-20% (character count, but wider glyphs) | | Chinese | -20-30% (character count) | | Arabic | +20-25% (plus RTL layout) | | Korean | -10-15% |

Rules:

• Buttons: Allow 40% extra width or use auto-sizing
• Tooltips: Max 60% of container width in English to allow expansion
• Never hard-code string widths
• Test with German and Arabic (longest expansion + RTL)

Cultural Sensitivity

• Humor: Puns and wordplay rarely translate. Stick to clear language.
• Formality: German, Japanese, Korean require formal register by default. "Du" vs "Sie" in German matters enormously.
• Color of language: "Red" means danger in the West, luck in China. Do not rely on color words alone.
• Dates and numbers: "1/2/2026" is January 2 (US) or February 1 (most of the world). Use explicit formats.
• Names: Not everyone has a first + last name structure. "Full name" is safer than "First name / Last name".
• Icons with text: Thumbs-up is offensive in parts of the Middle East. Always pair icons with text labels.

String Externalization

• Every user-facing string must be in a localization file, never hard-coded
• Use ICU MessageFormat for plurals: {count, plural, one {# item} other {# items}}
• Avoid string concatenation: "Welcome, " + name + "!" breaks in languages with different word order
• Use full sentences as translation units, not fragments

Sector Tone Guides

Fintech / Banking

• Voice: Trustworthy, precise, confident
• Tone keywords: Secure, clear, straightforward, reliable
• Do: "Your transfer of $500 to Alex is complete" / "Verify your identity to protect your account"
• Don't: "Woohoo, money sent!" / "We need to make sure you're really you lol"
• Button style: "Transfer funds", "Review statement", "Verify identity"
• Error style: "We couldn't complete this transfer. Your account has not been charged. [Try again]"

Healthcare / Wellness

• Voice: Empathetic, clear, reassuring
• Tone keywords: Caring, supportive, plain, calm
• Do: "Your appointment with Dr. Chen is confirmed for March 15 at 2:00 PM" / "Your results are ready. Tap to view."
• Don't: "Awesome, you're booked!" / "RESULTS ARE IN!!!"
• Button style: "Schedule appointment", "View results", "Message your care team"
• Error style: "We couldn't schedule your appointment. Dr. Chen is available at these other times: [alternatives]"

SaaS / Productivity

• Voice: Efficient, empowering, knowledgeable
• Tone keywords: Smart, capable, streamlined, no-nonsense
• Do: "Project created. Invite your team to get started." / "3 tasks due today"
• Don't: "YAY, new project!" / "You've got stuff to do"
• Button style: "Create project", "Invite team", "Start timer"
• Error style: "This project name is already taken. Try a different name. [Rename]"

Social / Community

• Voice: Warm, expressive, conversational
• Tone keywords: Friendly, personal, inclusive, fun
• Do: "Alex liked your photo" / "Share what's on your mind"
• Don't: "User 4829 interacted with your content" / "Compose a status update"
• Button style: "Share", "Like", "Comment", "Send a message"
• Error style: "We couldn't post that right now. Your draft is saved. [Try again]"

E-commerce / Marketplace

• Voice: Helpful, enthusiastic, trustworthy
• Tone keywords: Exciting, confident, reassuring, action-oriented
• Do: "Free shipping on orders over $50" / "Only 3 left in stock"
• Don't: "Shipping fees may apply based on various factors" / "Limited inventory warning"
• Button style: "Add to cart", "Buy now", "Apply code", "Complete purchase"
• Error style: "This item just sold out. We'll notify you when it's back. [Get notified]"

Education / EdTech

• Voice: Encouraging, patient, clear
• Tone keywords: Supportive, motivating, structured, approachable
• Do: "Great work! You completed 3 of 5 lessons." / "Pick up where you left off"
• Don't: "CRUSHING IT" / "Resume incomplete module"
• Button style: "Start lesson", "Continue learning", "Take quiz", "Review answers"
• Error style: "That answer didn't match. Review the hint and try again. [Show hint]"

Developer Tools

• Voice: Direct, precise, technical (but not jargon-heavy)
• Tone keywords: Efficient, accurate, no-fluff, respectful of expertise
• Do: "Build succeeded in 2.3s" / "API key created. Copy it now — it won't be shown again."
• Don't: "Yay, your build worked!" / "Here's your secret key thingy"
• Button style: "Deploy", "Create API key", "View logs", "Run tests"
• Error style: "Build failed: missing dependency lodash@4.17. Run npm install lodash to fix. [View full log]"

Gaming / Entertainment

• Voice: Energetic, immersive, personality-forward
• Tone keywords: Exciting, playful, dramatic, rewarding
• Do: "New high score! You beat your record by 200 points." / "Ready for the next challenge?"
• Don't: "Score updated in database" / "Proceed to next level"
• Button style: "Play now", "Challenge a friend", "Claim reward", "Continue quest"
• Error style: "Connection lost. Your progress is saved. [Reconnect]"

Real Estate / Property

• Voice: Professional, informative, aspirational
• Tone keywords: Trustworthy, detailed, approachable, knowledgeable
• Do: "3 new listings match your search" / "Schedule a tour of 123 Oak Street"
• Don't: "OMG new houses!" / "Initiate property viewing request"
• Button style: "Schedule tour", "Save listing", "Contact agent", "Get pre-approved"
• Error style: "This listing is no longer available. Here are similar homes nearby. [View similar]"

Travel / Hospitality

• Voice: Inspiring, helpful, warm
• Tone keywords: Adventurous, reassuring, personal, anticipatory
• Do: "Your trip to Tokyo is confirmed. 14 days to go!" / "Explore things to do near your hotel"
• Don't: "Booking reference confirmed" / "Ancillary activity discovery module"
• Button style: "Book now", "Explore destinations", "Check availability", "Add to trip"
• Error style: "These dates just got booked. Try nearby dates — we found 5 options. [View alternatives]"

Reference Architecture

| File | Contents | Use When | |------|----------|----------| | references/button-label-templates.md | 200+ button label templates organized by action type: primary, destructive, navigation, toggle, social, commerce, file, communication. Each with tone variants, character counts, when-to-use guidance, anti-patterns, and i18n notes. | Writing button labels. Choosing between "Save" vs "Save changes" vs "Update". Standardizing CTAs across a product. | | references/error-success-messages.md | 200+ error and success message templates: validation, system, permission, business logic errors. Success confirmations for every common action. Each with headline + body + recovery action + ARIA announcement. | Writing error messages. Creating success confirmations. Building a toast/notification system. Ensuring accessible error handling. | | references/empty-state-copy.md | 150+ empty state copy templates: first-use, no-results, cleared, error, permission states. By component: inbox, dashboard, list, table, search, notifications, activity, calendar, kanban, files, chat. Each with headline, body, CTA, illustration suggestion, tone variants. | Designing empty states. Writing first-use experiences. Creating no-results messages. Handling permission-gated blank screens. | | references/onboarding-permission-copy.md | 150+ onboarding and permission copy templates: welcome screens, profile setup, feature tours, permission requests (notifications, location, camera, etc.), pre-permission priming, progressive disclosure, activation prompts. Each with headline, body, primary/secondary CTA, visual suggestion. | Designing onboarding flows. Writing permission request screens. Creating feature tours. Building activation sequences. | | references/notification-tooltip-copy.md | 200+ notification, tooltip, and contextual help templates: push notifications, in-app notifications, toasts, tooltips, helper text, confirmation dialogs, loading messages, changelog entries. Each with text template, character limit, tone, timing. | Writing push notifications. Creating tooltip copy. Building confirmation dialogs. Writing loading states. Composing changelog entries. |

How to Use This Skill

Quick Lookup

"I need a button label for [action]" — Go to button-label-templates.md, find the action

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phazurlabs
• Source: phazurlabs/sumi
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.