From harness-claude
Applies microcopy principles—clarity, brevity, human voice, active voice—for UI text like buttons, errors, tooltips, notifications. Guides writing/reviewing short UI copy, not marketing/docs.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeThis skill uses the workspace's default tool permissions.
> Microcopy principles — clarity, brevity, human voice, active voice, and the core rules all UI text follows
Crafts production-ready UI microcopy: button labels, error messages, tooltips, empty states, onboarding flows, and confirmation dialogs. For in-product text only.
Improves unclear UX copy, error messages, microcopy, labels, and instructions for better interface clarity. Useful when refining confusing text or bad UX writing.
Writes and reviews UX copy for microcopy, error messages, empty states, CTAs, confirmations, tooltips, loading states, and onboarding. Use /ux-copy with context or auto-triggers on copy queries.
Share bugs, ideas, or general feedback.
Microcopy principles — clarity, brevity, human voice, active voice, and the core rules all UI text follows
Lead with the user's goal, not the system's action. Microcopy should reflect what the user is trying to accomplish, not what the software is doing behind the scenes. Stripe's checkout button says "Pay $49.99" -- the user's goal -- not "Submit payment request" -- the system's action. GitHub says "Create repository" not "Initialize new remote Git repository." Apple says "Set Up Face ID" not "Enroll biometric authentication." The test: read the label out loud and ask whether the user or the system is the subject.
Use first and second person for human voice. UI text should feel like a conversation between the product and the person using it. Use "you" and "your" to address the user directly. Use "we" when the product takes responsibility. Slack says "You have 3 unread messages" not "There are 3 unread messages in the channel." Notion says "Your workspace is ready" not "Workspace initialization complete." The shift from third person to second person transforms robotic status reports into human communication. Reserve third person for referring to other users: "Jordan commented on your pull request."
Keep UI text under two lines -- if longer, restructure or use progressive disclosure. Screen real estate is finite and attention is scarcer. If a tooltip requires a paragraph, the feature is either poorly designed or the text needs a "Learn more" link to documentation. Slack's message action tooltips are one sentence maximum. GitHub's hover cards show the essential information with a link to the full profile. If you cannot say it in two lines, consider whether a modal, popover, or help page would serve the user better.
Front-load the keyword in every label. Users scan the first two words of any text element. The distinguishing word must come first. GitHub uses "Pull requests" not "List of pull requests." Apple's Settings uses "Notifications" not "Manage your notifications." In a sidebar with ten items, the first word of each item is the only word most users will read. Compare a settings menu: "Notification preferences / Account settings / Privacy controls" is scannable. "Manage your notification preferences / Change your account settings / Update your privacy controls" buries the keywords.
Use specific verbs over generic ones. Generic verbs -- "OK," "Submit," "Confirm," "Done" -- force the user to recall what the button does. Specific verbs name the action: "Save draft," "Delete project," "Send invitation," "Export CSV." Stripe uses "Add payment method" not "Continue." Linear uses "Create issue" not "OK." The most dangerous generic verb is "OK" in a destructive dialog -- the user may click without reading. GitHub's dialog says "Delete this repository" on the destructive button, making the consequence unmistakable.
Match the user's vocabulary -- test with the five-second rule. Show a piece of UI text to someone unfamiliar with the product for five seconds. If they cannot explain what it does, the vocabulary is wrong. Notion calls pages "pages" because that is what users call them -- not "document instances" or "content nodes." Figma calls design files "files" not "design artifacts." The corollary: use the term people would type into a search box to find this feature. If users search for "dark mode," do not label the setting "Appearance theme."
Write for the moment -- microcopy must make sense without reading the rest of the page. Every piece of microcopy exists in a context, but the user may not have read that context. A tooltip that says "Enable this" is useless without reading the label above it. Apple's Face ID setup says "Face ID is now set up" -- this is clear even if the user skipped every previous screen. A toast that says "Done!" communicates nothing. A toast that says "Project saved" communicates everything. Each text element should be independently comprehensible.
Eliminate filler words -- every word must earn its place. Count the words in your UI text. Now remove every word that does not change the meaning. "You have successfully saved your changes to the document" becomes "Changes saved." "Please enter your email address in the field below" becomes "Email." "Click the button below to continue to the next step" becomes "Continue." Stripe's payment confirmation is "Payment successful" -- two words that convey the full message. The rule: if removing a word does not change the meaning, remove it.
Different UI components have different spatial constraints. These limits are guidelines, not absolutes, but exceeding them is a strong signal that the text needs editing:
| Component | Target Length | Maximum Length | Example |
|---|---|---|---|
| Button label | 1-3 words | 4 words | "Save draft" |
| Tab label | 1-2 words | 3 words | "Activity" |
| Menu item | 2-4 words | 5 words | "Export as PDF" |
| Tooltip | 1 sentence | 80 characters | "Copy link to clipboard" |
| Toast / snackbar | 1-2 sentences | 120 characters | "Changes saved. Undo" |
| Placeholder text | 2-5 words | 40 characters | "Search issues..." |
| Form field label | 1-3 words | 4 words | "Email address" |
| Helper text | 1 sentence | 100 characters | "Must be at least 8 characters" |
| Error message | 1-2 sentences | 150 characters | "Password too short. Use 8+ chars." |
| Empty state | 2-3 sentences | 200 characters | "No projects yet. Create one to..." |
| Confirmation title | 3-6 words | 8 words | "Delete this project?" |
| Confirmation body | 1-2 sentences | 150 characters | "This will permanently remove..." |
The five-second test is the simplest usability test for microcopy. The process:
This test catches jargon, buried keywords, ambiguous labels, and text that requires context to understand. Run it on every new feature's key screens before launch. Stripe runs five-second tests on payment forms to verify that users understand what will happen when they click the primary button. The test costs almost nothing and catches the most severe microcopy failures.
When reviewing existing UI text, check each item against these criteria:
Confirmation dialogs are where microcopy matters most because the consequences are highest. The anatomy of a well-written confirmation dialog:
Title: State the action as a question. "Delete this project?" not "Are you sure?" The title must name the specific action and the specific object so the user does not need to read the body text.
Body: State the consequence in one sentence. "This will permanently delete 'Acme Dashboard' and all its contents. This action cannot be undone." Name the object being affected. State whether the action is reversible. Do not pad with pleasantries or unnecessary warnings.
Primary action button: Use the destructive verb, not "OK" or "Yes." "Delete project" makes the consequence explicit. Color the button red for destructive actions. GitHub uses this pattern consistently: the delete confirmation button says "Delete this repository" in red, and requires typing the repository name as additional friction.
Secondary action button: "Cancel" or "Keep project" -- the safe option. Never label both buttons with ambiguous text like "Yes" and "No" -- force the user to read the question to understand which is which.
When the UI reflects a state change, the microcopy must communicate what happened and what the current state is:
The Robot Voice. UI text written in third-person passive that sounds like it was generated by a system, not written by a human. "The operation has been completed successfully. The user's preferences have been updated accordingly." No user talks like this. No human would say this to another human. The fix: rewrite in second person active voice. "Your preferences are updated." Better: "Preferences saved." The robot voice appears most often in legacy enterprise software and in products where engineers write the UI text without a content review process.
The Wall of Text. A tooltip, dialog, or notification that contains an entire paragraph of explanation when one sentence would suffice. The user needed to know "Your trial ends in 3 days," but the dialog says: "Thank you for trying our product. Your free trial period, which began on January 15, 2024, is scheduled to expire in 3 days on January 28, 2024. To continue using all premium features without interruption, please upgrade your subscription by visiting the billing page in your account settings." The fix: lead with the essential information, link to details. "Trial ends in 3 days. Upgrade to keep premium features."
The Vague Verb. Buttons and actions that use generic verbs -- "Submit," "Process," "Confirm," "OK," "Done," "Go" -- that do not tell the user what will happen. A dialog with "OK" and "Cancel" forces the user to re-read the dialog to understand which button does what. The fix: name the specific action on every button. "Delete project" and "Keep project" instead of "OK" and "Cancel." "Send invitation" instead of "Submit." The most common offender: "Submit" on forms -- it should be "Create account," "Place order," "Send message," or whatever the form actually does.
The Redundant Label. Labels that repeat information already visible in context. A "Name" field inside a section titled "Your Name" with placeholder text "Enter your name" and helper text "Type your full name here." Each repetition adds visual noise without adding information. The fix: each text element should add new information. The section title provides context, the field label names the specific field, the placeholder shows format ("Jane Smith"), and helper text adds constraints ("As it appears on your ID").
Stripe's Checkout Flow. Stripe's payment form is a masterclass in microcopy economy. The card number field label is simply "Card number" -- not "Enter your credit or debit card number." The expiration field says "MM / YY" as placeholder text -- the format is the instruction. The CTA button says "Pay $49.99" -- specific verb, specific amount, no ambiguity. Error messages are equally precise: "Your card number is incomplete" (not "Invalid input"), "Your card was declined. Try a different payment method." (not "Payment failed"). Every piece of text serves exactly one purpose and uses the minimum words to do so. Stripe's checkout has been tested with millions of transactions, and the microcopy is a major reason for its industry-leading conversion rates.
GitHub's Pull Request Interface. GitHub's PR interface demonstrates consistent verb-noun patterns across dozens of actions: "Create pull request," "Request review," "Merge pull request," "Close pull request," "Link issue," "Add assignees." Every action button follows the same structure -- imperative verb plus specific object. The review states are equally precise: "Approved," "Changes requested," "Commented." Status labels front-load the state: "Open," "Closed," "Merged" -- single words that communicate instantly. The file change summary "Showing 3 changed files with 47 additions and 12 deletions" packs five data points into one scannable sentence.
Slack's Notification Patterns. Slack calibrates microcopy density to urgency. A direct message notification: "Jordan: Can you review the PR?" -- sender and message, nothing else. A channel mention: "#engineering -- Jordan mentioned you." An app notification: "Reminder: Team standup in 15 minutes." Each notification type has a distinct pattern optimized for scanning. Slack's threading microcopy is particularly effective: "3 replies" as a link below a message tells the user exactly what they will find if they click. The "also sent to #channel" indicator uses minimal text to convey a complex routing concept.
Notion's Progressive Disclosure. Notion demonstrates how microcopy adapts to expertise. A blank page shows "Press '/' for commands" -- teaching the core interaction in five words. The slash command menu labels are pure front-loaded keywords: "To-do list," "Heading 1," "Toggle list," "Quote." Each label is the feature name, not a description of the feature. Hover tooltips add keyboard shortcuts for power users without cluttering the primary label. The empty database shows "Click '+' to add a row" -- always one specific next action, never a paragraph of explanation. As users gain expertise, the microcopy recedes: empty pages stop showing the hint after repeated use.