Stats
Actions
Tags
From harness-claude
Makes UI text readable at a 6th-8th grade reading level by eliminating jargon, shortening sentences, and structuring for scanning. Useful for consumer product copy, error messages, onboarding, and help text.
How this skill is triggered — by the user, by Claude, or both
Slash command
/harness-claude:ux-plain-languageThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Plain language for UI — reading level targeting, jargon elimination, sentence structure for scanning
Plain language for UI — reading level targeting, jargon elimination, sentence structure for scanning
Target a sixth-to-eighth grade reading level for consumer products. The Flesch-Kincaid readability formula measures sentence length and syllable count. A sixth-grade reading level means average sentences of 12-15 words using common two-syllable words. This is not dumbing down -- it is optimizing for speed and comprehension. The Nielsen Norman Group found that even users with graduate degrees prefer content written at a lower reading level because it is faster to process. Use the Hemingway App or readability plugins to measure. Stripe's user-facing text consistently scores at grade 6-8 even when explaining complex payment concepts.
Replace jargon with common words. Every domain has its jargon, and that jargon feels natural to the team that builds the product. It does not feel natural to the user. Maintain a substitution list and enforce it in code reviews:
| Jargon | Plain alternative |
|---|---|
| utilize | use |
| initialize | start |
| terminate | end |
| authenticate | sign in |
| configure | set up |
| deploy | publish |
| propagate | spread / update |
| deprecated | no longer supported |
| payload | data |
| parameter | setting / option |
| execute | run |
| instantiate | create |
| invoke | call / use |
| persist | save |
| iterate | repeat / go through |
| synchronize | sync / update |
| enumerate | list |
| concatenate | combine / join |
| obfuscate | hide |
| remediate | fix |
Google's Material Design guidelines explicitly state: "Avoid technical jargon unless it is widely understood by your target audience." Notion calls pages "pages" because that is what users call them. GitHub uses "fork" but defines it on first encounter: "Fork -- create your own copy of this repository."
One idea per sentence. If a sentence contains a comma followed by a conjunction ("and," "but," "or"), it probably contains two ideas and should be split. "Your trial has expired and you need to upgrade to continue using premium features" becomes "Your trial has expired. Upgrade to keep premium features." The split improves scanning, comprehension, and translation. Translators work sentence by sentence -- compound sentences create ambiguity about which clause modifies which. Stripe's error messages follow single-idea sentences: "Your card was declined." "Try a different payment method."
Prefer concrete nouns over abstract ones. Abstract nouns force the reader to map the abstraction to something real. "Your uploaded resource" is abstract. "Your file" is concrete. "The authentication credential" is abstract. "Your password" is concrete. "The configuration parameters" is abstract. "Your settings" is concrete. Users think in concrete objects, not in system abstractions. Apple's Human Interface Guidelines consistently use concrete language: "your photo," "your message," "your password" -- never "the media asset," "the communication payload," "the credential."
Use the word the user would search for. If users search for "dark mode," label the setting "Dark mode" -- not "Appearance theme" or "Display preferences." If users search for "delete my account," the menu item should say "Delete account" -- not "Account deactivation" or "Terminate membership." Google runs search query analysis on their support pages to identify the terms users actually type, then maps those terms directly to feature labels and help articles. This principle extends to error messages: "No internet connection" is what users would type into a search engine, not "Network connectivity unavailable."
Define technical terms on first use when they cannot be avoided. Some terms have no plain alternative -- "two-factor authentication," "API key," "webhook" are genuinely specialized and the plain alternatives are longer and less precise. When these terms must appear in UI text, define them inline on first use. GitHub does this: "Fork -- create your own copy of this repository." Stripe does this: "API key -- a unique identifier that authenticates requests to Stripe's API." The definition should be one clause or one sentence. If the definition requires a paragraph, link to documentation instead.
Cut nominalizations -- use verb forms over noun forms. Nominalizations are verbs turned into nouns: "make a decision" instead of "decide," "perform an analysis" instead of "analyze," "send a notification" instead of "notify." Nominalizations add words without adding meaning. They make sentences longer, more abstract, and harder to scan. The fix is mechanical: find the nominalization, extract the verb, rebuild the sentence around the verb.
| Nominalization (wordy) | Verb form (concise) |
|---|---|
| make a selection | select |
| perform a search | search |
| carry out an installation | install |
| give authorization | authorize |
| reach a conclusion | conclude |
| take into consideration | consider |
| provide an explanation | explain |
| make an adjustment | adjust |
Different audiences tolerate different reading levels, but the principle is the same: write at the lowest level the content allows.
| Audience | Target Grade Level | Sentence Length | Example Product |
|---|---|---|---|
| General consumer | Grade 6-8 | 12-15 words | Airbnb, Instagram, Venmo |
| Prosumer / small business | Grade 8-10 | 15-20 words | Notion, Figma, Shopify |
| Developer tooling | Grade 10-12 | 20-25 words | Stripe API, GitHub API |
| Enterprise administration | Grade 10-12 | 15-20 words | AWS Console, Salesforce |
Even at the developer level, plain language principles apply. Stripe's API documentation is technical but avoids unnecessary complexity: "Create a PaymentIntent" not "Instantiate a PaymentIntent object by invoking the creation endpoint." The technical audience does not need simpler concepts -- they need simpler phrasing of complex concepts.
Research consistently shows that comprehension drops as sentence length increases:
For UI text, the maximum sentence length should be 20 words. For mobile UI (where screen width constrains line length), target 12-15 words. For tooltips and toasts, target 8-12 words. Count the words in every sentence you write and split anything over the limit.
To audit existing UI text for plain language compliance:
Gov.uk performed this audit across their entire government website and reduced the average reading level from grade 14 to grade 8. Support ticket volume dropped 30% in the first year after the plain language rewrite.
The Thesaurus Trap. Using unusual synonyms to avoid repeating common words. "Utilize" instead of "use" the second time, then "leverage" the third time, then "employ" the fourth. This variety confuses rather than clarifies -- the reader wonders if each synonym means something different. In UI text, consistency trumps variety. If the action is "save," use "save" every time. If the object is "project," call it "project" everywhere. Stripe uses "customer" consistently throughout their entire dashboard -- never "client," "user," or "account holder."
The Legalese Leak. Legal or compliance language that bleeds into user-facing text. "By proceeding, you acknowledge and agree that the aforementioned data will be processed in accordance with our privacy policy as amended from time to time." No user reads this, and those who try cannot parse it. The fix: write the legal concept in plain language first, then have legal review for accuracy. "We'll use your data as described in our privacy policy" says the same thing in 12 words instead of 30. Apple's privacy labels accomplish this -- "Data Used to Track You" is legally accurate and readable at a fourth-grade level.
The Acronym Soup. UI text filled with undefined acronyms: "Configure your SSO via SAML or OIDC in the IAM console." Each acronym is a speed bump that forces the reader to decode or search. The rule: spell out every acronym on first use in any given screen. If the screen uses more than two acronyms, the text is too technical for the audience. AWS documentation improves when it says "Single Sign-On (SSO)" on first mention, then uses "SSO" thereafter. For UI text (not documentation), consider whether the acronym is necessary at all -- "Sign in with your company account" may be better than "Configure SSO."
The Passive Abstraction. Combining passive voice with abstract nouns to create maximally opaque sentences. "The configuration has been updated with the newly specified parameters" instead of "Your settings are saved." "An error was encountered during the processing of your request" instead of "Something went wrong. Try again." These sentences require the reader to mentally restructure the grammar to extract meaning. The fix: find the actor, find the action, put them in subject-verb order with concrete nouns.
Gov.uk's Plain Language Transformation. The UK Government Digital Service rewrote the entire gov.uk website using plain language principles. Before: "If you are a foreign national seeking indefinite leave to remain in the United Kingdom, you must demonstrate that you have met the residency requirement." After: "To stay in the UK permanently, you need to have lived here for a certain amount of time." The before version reads at grade 16. The after version reads at grade 8. Both are legally accurate. The plain language version reduced phone calls to the immigration helpline by 35% because users could understand the requirements without assistance.
Stripe's Error Messages. Stripe's payment error messages demonstrate plain language under pressure. When a card is declined, users are stressed and need immediate clarity. Stripe's messages: "Your card was declined. Try a different payment method or contact your bank." "Your card's expiration year is invalid." "Your card number is incomplete." Each message names the specific problem and (when possible) provides a specific next action. Compare with a legacy payment processor: "Error code 4001: Transaction declined by issuing bank. Please consult your financial institution regarding the status of your account." Same information, but the plain language version is actionable without decoding.
Notion's Feature Naming. Notion's naming conventions demonstrate user-centered vocabulary. The product uses "page" (not "document"), "block" (not "content element"), "template" (not "scaffolding"), "share" (not "publish" or "distribute"), and "comment" (not "annotation" or "feedback item"). Each term was chosen because it maps to a concept users already understand. When Notion introduced databases, they called them "databases" -- a word every user knows -- rather than "structured data collections" or "relational tables." The simplicity of the naming makes a complex product feel approachable.
Apple's Privacy Labels. Apple's App Store privacy labels translate complex data collection practices into plain language that any user can understand. Instead of "This application processes personally identifiable information for advertising attribution purposes," Apple's labels say "Data Used to Track You" and "Data Linked to You." Each label category uses a concrete icon and a two-to-four word description. The labels read at a fourth-grade level while remaining legally accurate -- proof that legal concepts can be expressed in plain language without sacrificing precision.
npx claudepluginhub intense-visions/harness-engineering --plugin harness-claudeReviews and writes user-facing text for plain language accessibility. Covers interface copy, error messages, instructions, forms, and help content for diverse readers.
Guides writing clear, concise, human-voiced UI microcopy for buttons, errors, tooltips, and empty states.
Writes button labels, error messages, placeholder text, empty states, and tooltips that are specific, actionable, and honest. Helps reduce user friction and support contacts.