From 2061c7b938f6f78651caa63b5f5dd27840a3d4ad Mon Sep 17 00:00:00 2001 From: Julia Mnizhek Date: Tue, 23 Jun 2026 21:34:55 +0200 Subject: [PATCH 1/6] [docs] add separate Content section --- website/docs/.vitepress/sidebarConfig.ts | 84 ++++++++++++++++++- website/docs/content/buttons/buttons.md | 3 + .../content-principles/content-principles.md | 3 + website/docs/content/errors/errors.md | 3 + website/docs/content/feedback/feedback.md | 3 + website/docs/content/grammar/grammar.md | 3 + website/docs/content/lists/lists.md | 3 + website/docs/content/modals/modals.md | 3 + website/docs/content/onboarding/onboarding.md | 3 + .../docs/content/placeholders/placeholders.md | 3 + .../pricing-and-sales/pricing-and-sales.md | 3 + .../content/system-states/system-states.md | 3 + .../voice-and-style/voice-and-style.md | 3 + website/docs/content/warnings/warnings.md | 3 + 14 files changed, 122 insertions(+), 1 deletion(-) create mode 100644 website/docs/content/buttons/buttons.md create mode 100644 website/docs/content/content-principles/content-principles.md create mode 100644 website/docs/content/errors/errors.md create mode 100644 website/docs/content/feedback/feedback.md create mode 100644 website/docs/content/grammar/grammar.md create mode 100644 website/docs/content/lists/lists.md create mode 100644 website/docs/content/modals/modals.md create mode 100644 website/docs/content/onboarding/onboarding.md create mode 100644 website/docs/content/placeholders/placeholders.md create mode 100644 website/docs/content/pricing-and-sales/pricing-and-sales.md create mode 100644 website/docs/content/system-states/system-states.md create mode 100644 website/docs/content/voice-and-style/voice-and-style.md create mode 100644 website/docs/content/warnings/warnings.md diff --git a/website/docs/.vitepress/sidebarConfig.ts b/website/docs/.vitepress/sidebarConfig.ts index a5f9562fe8..9c72c72a31 100644 --- a/website/docs/.vitepress/sidebarConfig.ts +++ b/website/docs/.vitepress/sidebarConfig.ts @@ -109,10 +109,30 @@ export const sideBarConfig: SidebarConfig = [ }, ], }, + ], + }, + { + text: 'Content', + items: [ + { + link: '/content/content-principles/content-principles', + activeMatch: '/content/content-principles/', + text: 'Content principles', + }, { - text: 'Content', + text: 'Style & grammar', collapsed: true, items: [ + { + link: '/content/voice-and-style/voice-and-style', + activeMatch: '/content/voice-and-style/', + text: 'Voice and style', + }, + { + link: '/content/grammar/grammar', + activeMatch: '/content/grammar/', + text: 'Grammar', + }, { link: '/content/capitalization/capitalization', activeMatch: '/content/capitalization/', @@ -145,6 +165,68 @@ export const sideBarConfig: SidebarConfig = [ }, ], }, + { + text: 'UX patterns', + collapsed: true, + items: [ + { + link: '/content/onboarding/onboarding', + activeMatch: '/content/onboarding/', + text: 'Onboarding', + }, + { + link: '/content/pricing-and-sales/pricing-and-sales', + activeMatch: '/content/pricing-and-sales/', + text: 'Pricing and sales', + }, + { + link: '/content/feedback/feedback', + activeMatch: '/content/feedback/', + text: 'Feedback', + }, + { + link: '/content/system-states/system-states', + activeMatch: '/content/system-states/', + text: 'System states', + }, + { + link: '/content/warnings/warnings', + activeMatch: '/content/warnings/', + text: 'Warnings', + }, + { + link: '/content/errors/errors', + activeMatch: '/content/errors/', + text: 'Errors', + }, + { + link: '/content/lists/lists', + activeMatch: '/content/lists/', + text: 'Lists', + }, + { + link: '/content/modals/modals', + activeMatch: '/content/modals/', + text: 'Modals', + }, + ], + }, + { + text: 'UI elements', + collapsed: true, + items: [ + { + link: '/content/placeholders/placeholders', + activeMatch: '/content/placeholders/', + text: 'Placeholders', + }, + { + link: '/content/buttons/buttons', + activeMatch: '/content/buttons/', + text: 'Buttons', + }, + ], + }, ], }, { diff --git a/website/docs/content/buttons/buttons.md b/website/docs/content/buttons/buttons.md new file mode 100644 index 0000000000..fb77a45273 --- /dev/null +++ b/website/docs/content/buttons/buttons.md @@ -0,0 +1,3 @@ +--- +title: Buttons +--- diff --git a/website/docs/content/content-principles/content-principles.md b/website/docs/content/content-principles/content-principles.md new file mode 100644 index 0000000000..7f9f5dce67 --- /dev/null +++ b/website/docs/content/content-principles/content-principles.md @@ -0,0 +1,3 @@ +--- +title: Content principles +--- diff --git a/website/docs/content/errors/errors.md b/website/docs/content/errors/errors.md new file mode 100644 index 0000000000..71f1725a31 --- /dev/null +++ b/website/docs/content/errors/errors.md @@ -0,0 +1,3 @@ +--- +title: Errors +--- diff --git a/website/docs/content/feedback/feedback.md b/website/docs/content/feedback/feedback.md new file mode 100644 index 0000000000..92bf97996b --- /dev/null +++ b/website/docs/content/feedback/feedback.md @@ -0,0 +1,3 @@ +--- +title: Feedback +--- diff --git a/website/docs/content/grammar/grammar.md b/website/docs/content/grammar/grammar.md new file mode 100644 index 0000000000..a77bf2a9b5 --- /dev/null +++ b/website/docs/content/grammar/grammar.md @@ -0,0 +1,3 @@ +--- +title: Grammar +--- diff --git a/website/docs/content/lists/lists.md b/website/docs/content/lists/lists.md new file mode 100644 index 0000000000..a06cd19084 --- /dev/null +++ b/website/docs/content/lists/lists.md @@ -0,0 +1,3 @@ +--- +title: Lists +--- diff --git a/website/docs/content/modals/modals.md b/website/docs/content/modals/modals.md new file mode 100644 index 0000000000..943a329bda --- /dev/null +++ b/website/docs/content/modals/modals.md @@ -0,0 +1,3 @@ +--- +title: Modals +--- diff --git a/website/docs/content/onboarding/onboarding.md b/website/docs/content/onboarding/onboarding.md new file mode 100644 index 0000000000..f0945361ff --- /dev/null +++ b/website/docs/content/onboarding/onboarding.md @@ -0,0 +1,3 @@ +--- +title: Onboarding +--- diff --git a/website/docs/content/placeholders/placeholders.md b/website/docs/content/placeholders/placeholders.md new file mode 100644 index 0000000000..151cfdaf3a --- /dev/null +++ b/website/docs/content/placeholders/placeholders.md @@ -0,0 +1,3 @@ +--- +title: Placeholders +--- diff --git a/website/docs/content/pricing-and-sales/pricing-and-sales.md b/website/docs/content/pricing-and-sales/pricing-and-sales.md new file mode 100644 index 0000000000..1e11b2fce4 --- /dev/null +++ b/website/docs/content/pricing-and-sales/pricing-and-sales.md @@ -0,0 +1,3 @@ +--- +title: Pricing and sales +--- diff --git a/website/docs/content/system-states/system-states.md b/website/docs/content/system-states/system-states.md new file mode 100644 index 0000000000..34bef26170 --- /dev/null +++ b/website/docs/content/system-states/system-states.md @@ -0,0 +1,3 @@ +--- +title: System states +--- diff --git a/website/docs/content/voice-and-style/voice-and-style.md b/website/docs/content/voice-and-style/voice-and-style.md new file mode 100644 index 0000000000..635e1467ca --- /dev/null +++ b/website/docs/content/voice-and-style/voice-and-style.md @@ -0,0 +1,3 @@ +--- +title: Voice and style +--- diff --git a/website/docs/content/warnings/warnings.md b/website/docs/content/warnings/warnings.md new file mode 100644 index 0000000000..7db2e87909 --- /dev/null +++ b/website/docs/content/warnings/warnings.md @@ -0,0 +1,3 @@ +--- +title: Warnings +--- From 20c29481207f3027642b809c1a5a31053ecae96f Mon Sep 17 00:00:00 2001 From: Julia Mnizhek Date: Tue, 23 Jun 2026 22:10:59 +0200 Subject: [PATCH 2/6] [docs] add info from Nastya --- website/docs/content/buttons/buttons.md | 48 +++ .../content-principles/content-principles.md | 331 ++++++++++++++++++ website/docs/content/errors/errors.md | 110 ++++++ website/docs/content/feedback/feedback.md | 19 + website/docs/content/grammar/grammar.md | 230 ++++++++++++ website/docs/content/lists/lists.md | 21 ++ website/docs/content/modals/modals.md | 42 +++ website/docs/content/onboarding/onboarding.md | 42 +++ .../docs/content/placeholders/placeholders.md | 27 ++ .../pricing-and-sales/pricing-and-sales.md | 49 +++ .../content/system-states/system-states.md | 66 ++++ .../voice-and-style/voice-and-style.md | 316 +++++++++++++++++ website/docs/content/warnings/warnings.md | 34 ++ 13 files changed, 1335 insertions(+) diff --git a/website/docs/content/buttons/buttons.md b/website/docs/content/buttons/buttons.md index fb77a45273..a6ba4c30e6 100644 --- a/website/docs/content/buttons/buttons.md +++ b/website/docs/content/buttons/buttons.md @@ -1,3 +1,51 @@ --- title: Buttons --- + +Button labels should feel like the start of a new action — specific, verb-led, and connected to the surrounding context. + +## Consider context + +- Focus your attention on the expected outcome (What is the user trying to accomplish?) +- Connect the action with the result (What happens before? What happens after? "Can we say [Update] here, if it was [Renew] on the previous/next step?") +- Connect the action with the title or other text (What's the context — modal, form, standalone button? Is everything clearly connected?) + +## Writing buttons + +The button should feel like a start of a new action and kind of a forward motion. Use verbs such as: + +- Create / launch / delete / connect / send / view +- Learn more (use sparingly) + +ALWAYS match the button to the title. + + + + + + +- Mostly use verb + noun format (e.g., "Save document" not just "Save"). Always consider context: it can be "Export all data" if there are multiple options to choose from AND "Export data" when it's just one option. +- Clearly indicate the result of clicking the button. +- Don't use articles. +- Use sentence case. +- Try to keep the text under 3 words. +- Avoid vague labels like "Submit" or "Click here". + + + + + + +Good example: Create account (Registration flow — clear outcome for the user) + +## Corner cases + +If the button is passive (Privacy policy, About us, etc.) then it's most likely to be a link. If you absolutely need a button, say "Read privacy policy" or "View terms of service". diff --git a/website/docs/content/content-principles/content-principles.md b/website/docs/content/content-principles/content-principles.md index 7f9f5dce67..922d0a350b 100644 --- a/website/docs/content/content-principles/content-principles.md +++ b/website/docs/content/content-principles/content-principles.md @@ -1,3 +1,334 @@ --- title: Content principles --- + +## Use user-centered language + +People don't care about your 50th new cool feature. They want their task complete as quickly and easily as possible. All writing must prioritize user goals and comprehension over business jargon or marketing speak. + + + + + + +Eliminate "feature-speak". Always make sure the texts show benefit for the user. + + + + + + +Cut corporate filler — phrases that exist to sound official rather than communicate something. In the context of web content and quick scanning you don't sound polite, you sound annoying. + + + + + + +## Write for scannability + +People on the internet don't read like they read books. They scan, usually in the F pattern. That's why it's important to: + +- Put important information at the front (front-loading). +- Keep sentences under 20 words when possible. If you need to take a breath to finish reading the sentence out loud — it's a bad sign. +- Have one idea per sentence, split complex thoughts. + + + + + + +- Use actionable language. Every button, link, and CTA must clearly indicate what happens when clicked. Never say "Click here". + +Good examples: Save draft, Publish article, Delete account. + +**Got it** — Exception. Use only for dismissible informational modals where no critical action is taken and the user is simply acknowledging they've read the information. + + + + + + +- Avoid using "We" in most cases. Focus on the user's experience. + + + + + + +- Only use "we" in cases when other wording feels unnatural or too wordy. + + + + + + +- Avoid "please" unless asking for something optional or inconvenient. + + + + + + +- Avoid passive voice unless the action is product-side. + + + + + + +- Naturally connect texts within one UI element — the title, body, and button should form one coherent thought. + + + + + + +- Cut unnecessary adverbs ("successfully") or those that reflect a writer's opinion ("quickly", "easily"). +- Use parallel structure in lists. + + + + + + +- DO NOT break semantic blocks. Keep related information together. + + + + + + +## Conversational writing + +Write in a way a person talks to another person, not a system. + +- Use contractions — they reduce formality without reducing clarity. Be mindful of how many contractions you use in a sentence. Too many contractions can make things difficult to read. + + + + + + +It's okay to use a full version if you want to highlight an action: + +> It will be permanently deleted. + +- Read your text aloud. If it sounds unnatural spoken, rewrite it. Passive, overly formal, or instruction-heavy sentences fail this test immediately. + + + + + + +- Match the emotional register of the moment. Conversational doesn't mean casual. An error moment calls for calm and direct tone, a success moment can be warmer. + +## Plain language + +Writing for a 6th-grade reading level on the Flesch-Kincaid readability scale includes more people. Write with short sentences, use simpler nouns, avoid adverbs and adjectives unless they carry real meaning. Use simple verb tenses (past, present, future) and active voice. + +You can check readability using [hemingwayapp.com](https://hemingwayapp.com/). + +## Consistency + +Within a single tool, tab, window: + +- Use the same term for the same concept. Don't create new notions without need. +- Don't use synonyms for the same actions, e.g. "delete" and "remove". +- Keep button patterns consistent: all verbs only or all verb+noun. + +## Is content the issue? + +Copy won't ever make up for poor experience design. Sometimes removing stuff, adding or revising interactions, or leaning on visual design works better. + +## Testing + +What you wrote will probably make sense to your team. Show it to someone who knows nothing about what you're working on. + +## UX design principles + +Several UX laws apply directly to text — they're based on how the human brain processes information. + +### Cognitive load and Miller's law + +The amount of information presented at once should be manageable. Break information into short paragraphs, use headings, and control the number of decisions users are asked to make at once. + +### Selective attention + +Important info should always be visible and close to a CTA or an input field. No matter how well you describe how something works in a hint text or a tooltip, users will most likely never see it unless they really need to. + +### Serial position effect + +Placing key information or actions in the beginning or the end will make it more memorable. Never hide the most important thing in the middle of a list, paragraph, or window. + +## Localization + +If your content will be localized, consider the following: + +- Avoid idioms and word play that don't translate well. +- Avoid colloquial language and slang. +- Remember about character limits and allow for extra space. English text tends to expand to 30% and more in translation. +- When adding variables into text, remember that languages have different structures. What looks okay in UI in English can simply not work in another language. +- Try to use gender-neutral language. + + + + + + +- (For frontend) Don't break one sentence into several parts: word order in many languages does not match word order in English. + +If in doubt, always consult with localization managers. + +## Accessibility and inclusivity + +### Alt text + +Add alt text only if the image brings additional value to the rest of the content. Do not use alt text for purely decorative images (graphics on a landing page, charts or graphs with no real data). + +- Describe the image as objectively as possible +- Provide context to the image +- Use sentence case +- Capitalize proper nouns + + + + + + +### Age + +Avoid ageist terms. When age context is needed, describe it neutrally. See the Glossary. + +### Race and ethnicity + +Default to the generally accepted descriptors "person of color," "POC," or "BIPOC". See the Glossary. + +### Words and phrases to avoid + +- Confusing and offensive acronyms (WTF, WTH, KYS, IYKYK, STFU, KMA, FU, FFS) +- Profanity and curse words +- Innuendos (sexual-related innuendos, dirty jokes, etc.) +- Things that can set off a safe-search filter (bomb, knife, gun, sex, etc.) + +### Gender and sexuality + +- Default to "they/their" and "you/your" for pronouns. Avoid "him/his" or "she/her" — never assume how someone identifies. When in doubt, use their name. If they have pronouns listed publicly, you may use those. +- Use gender-neutral terms: businessperson over businessman or businesswoman. + +### Disabilities and mental health + +Some phrases may seem ordinary but can be insensitive. Avoid these as descriptions: + +- blind +- crazy +- cripple or crippling +- lame + +## Creating terms and definitions + +Define a word in simple and familiar terms. A definition should not make the reader look up explanations of other words. + +### DO NOT use the same term to define a term + + + + + + +### When referencing another term, use the term itself, not its definition + + + + + + +### A definition of a noun term cannot be a verb + + + + + diff --git a/website/docs/content/errors/errors.md b/website/docs/content/errors/errors.md index 71f1725a31..abd6723281 100644 --- a/website/docs/content/errors/errors.md +++ b/website/docs/content/errors/errors.md @@ -1,3 +1,113 @@ --- title: Errors --- + +How to write calm, blame-free error messages that help users recover quickly. + +## Prevent errors + +Showing error messages should be a last resort. When you face creating one, ask yourself "Can we prevent this error from happening?" The system should be smart enough to minimize errors in user input or actions. For example, if you expect a particular data format, use an input mask. + +## Anatomy of an error message + +Regardless of the design component or message length, the most comprehensive error messages include three parts: + +1. What happened +2. The underlying cause (if possible) +3. How to fix it + +### What happened + +This should be the first part of the message, like in a headline (if the UI element allows). Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user. + + + + + + +### The cause + +It's helpful to have an explanation of why something happened — it can increase the user's understanding of the issue. + + + + + + +### How to fix it + +This part tells the user what they can do about it. Offer a step-by-step resolution in the most simple and actionable way. If there's nothing for them to do, then explain what the product is doing. Offer a path forward within the error state itself, such as a "Try again" or "Go back" button. Linking to a help article can be useful, but only if that article is specific and descriptive to the error's use case. + + + + + + +## Main principles + +### Center the language around user goals, not system constraints + +Sometimes it seems like the best way to resolve an error is to explain the constraints of the system to the user. But most users don't care about the constraints of the system — they care about accomplishing their goals. Center the language around what the user is trying to accomplish, why that didn't happen, and how they might resolve the error. + +### Use plain language, and avoid jargon + +Users may not understand server architecture or client-side queries. Don't use internal product or technical jargon in most cases. However, technical terms are different than jargon. If you're confident that your audience would be readily familiar with technical terms, and if such terms are relevant to the message, you can include them. + +### Use positive framing to keep the focus on what users can do + +While a user will want to know what went wrong, be as clear as possible about what they can do to fix the error, or provide them with an alternative workaround. Sometimes it's simple ("try again in a few minutes") and sometimes the only solution can be time-intensive or potentially frustrating ("contact your IT administrator"). Avoid putting the focus on the problem, what a user can't do, or what they did incorrectly. Instead, offer context and help people understand what they can do. + +### Create error states that are specific to each case whenever possible + +It may be tempting to write a catch-all error message to accommodate dozens of similar scenarios, but that will tend to be wordier and less concise. Creating multiple, more specific error messages takes additional effort, but it ultimately creates a better user experience. + +### While the error should be specific, use generic language + +Generic language allows for better localization, and it also reduces the need to write many different versions of messages for similar use cases. It's usually unnecessary to include specific filenames, usernames, or folders because a user can get that context from elsewhere in the UI. + +## Writing the message + +**Voltage: low** + +Lowest voltage in UI. Always stick to the point — avoid overly formal, technical, or alarming styles. Stay calm and blame-free. Every error should tell the user what to do next, not just what went wrong. + +Use "please" and "sorry" only when: + +- We are to blame for an error (e.g., maintenance on our servers, technical issues) +- The user skipped a required field (we prevent them from continuing) + +### Critical + + + + + + +### Non-critical + + + + + diff --git a/website/docs/content/feedback/feedback.md b/website/docs/content/feedback/feedback.md index 92bf97996b..c6a61cfa4e 100644 --- a/website/docs/content/feedback/feedback.md +++ b/website/docs/content/feedback/feedback.md @@ -1,3 +1,22 @@ --- title: Feedback --- + +How to ask users for their opinion without sounding like a survey form. + +## Voice + +**Voltage: medium** + +Move away from formal wording that feels lifeless. Keep it simple and friendly — write like a person, not a system. Avoid survey-speak ("evaluate," "rate your experience") in favor of plain, human phrasing. + + + + + diff --git a/website/docs/content/grammar/grammar.md b/website/docs/content/grammar/grammar.md index a77bf2a9b5..00ea2370fc 100644 --- a/website/docs/content/grammar/grammar.md +++ b/website/docs/content/grammar/grammar.md @@ -1,3 +1,233 @@ --- title: Grammar --- + +## Tenses + +In general, use simple verb tenses: past, present, and future. Use simple future tense to describe the result of an action or instant process that's happening now, or something that will occur in the actual future. + +### Why use simple verb tenses + +- They use fewer words and are more concise. +- They can make content easier to scan and faster to read. +- Simple tenses are easier to understand — more than 20% of U.S. residents speak a language other than English at home. +- Present tense improves readability scores. + +### What's not simple tense + +If any of the following comes before the verb in a sentence, it's not simple tense: + +- Was/wasn't, were/weren't +- Has/hasn't, have/haven't +- Is/isn't, are/aren't +- Be +- If the verb in a sentence ends in "-ing" + +## Active and passive voice + +Use active voice in most cases and use passive voice sparingly. + +### Active voice + +In an active sentence, it's clear who's doing what. The actor is the subject, and the subject of the sentence is doing something. + + + + + + +### Passive voice + +At times, active voice can sound too harshly or keep focus on something that's less important in the context. In these cases, switch to passive voice. This separates the actor from the action to soften a sentence. + + + + + + +### Avoid passive voice by reframing the focus + +You can usually reframe a message to focus on the object, or on the actions someone could take, as another way to avoid passive voice. + + + + + + +## Spelling + +Always use American English (AmE) spelling unless localizing content for specific regions. + +- "yse"/"ise" → "yze"/"ize": analyze, not analyse; organize, not organise +- "our" → "or": color, not colour; humor, not humour +- double L → single L: traveled, not travelled; canceled, not cancelled +- "ence" → "ense": defense, not defence + +## Pronouns + +### Referring to the user + +Avoid calling users "users" when talking to them. + +### Second person + +Most of the time, use second person (you, your, you're) to address users and services. + +### First person + +Use first person (me, I, my) only in these situations: + +- User takes the action in the interface or answers a question they've been asked directly. Imagine you are the user "saying" these lines. Does a CTA feel natural ("Go to my profile" ✓) or not ("Start your free trial" ✗)? +- When additional sensitivity is necessary, or to indicate privacy. +- When there's a legal need to use first person to ask for consent. + + + + + + +Sometimes it's okay to use "we" or "us" to mean "Semrush": + +- "We're sorry" (for a critical error) +- "Help us improve this feature" (requesting feedback) + +### Singular they + +Usually, we don't need to specify the gender of our users. Do not use "he/she", "(s)he". Use "they" in proper grammatical form (they, them, their, theirs, themselves, themself). + +## Numbers + +- Use numerals rather than spelling out numbers — except for years. + +Good examples: Succeed in SEO in 7 steps. / 2015 was a standout year for the company. + +- For numbers above 999, use commas between each set of three digits. + +Good examples: 10,000 / 5,999,999 + +- For decimals, use periods. + +Good example: 39.99 + +- Use the percent symbol (%) rather than spelling out the word "percent." Don't add a space before the character. + +Good example: 25% + +- Spell out large round numbers. Abbreviate to K, M, and B only when space is extremely limited, like display ads or email subject lines. Always capitalize them. Don't include a space between K, M, or B and the number. + +Good examples: 4 thousand / 81 million / 2.5 billion / 90M + +- Keep numbers spelled out where it's common usage. + +Good example: Connect third-party apps + +- For a range of numbers, use the en dash. + +Good example: 3–5 days + +- For a range with a number sign (#), omit space. + +Good example: #4–9 + +- When a number is used as an adjective, use a hyphen. + +Good example: 7-day trial + +## Dates and time + +### Dates + +Writing dates using only numbers causes readability problems across regions. Use words for months. + +- Uppercase AM and PM and do not use periods. + +Good example: The session will run from 10 AM until 2 PM. + +- Do not abbreviate the month in text. + +Good example: We saw a large traffic spike in January 2023. + +- Do not add ordinals (st, th, nd) to dates. + + + + + + +### Time + +- Do not use :00 with whole numbers. +- For a range of time, use an en dash without spaces. Omit AM/PM on the first time if it matches the last. +- When translating to 24-hour time, omit AM and PM (e.g., 17:15). +- Adjust time zone for daylight savings and standard time changes. + +Good examples: EST (during standard time) / EDT (during daylight savings time) + +- Specify the time zone and use abbreviations after first reference. + +Good examples: 11 AM EST (Eastern Standard Time) / After first reference: 12 PM EST + +Avoid time zones unless absolutely necessary — dynamically convert to the user's time zone if possible. + +### Elapsed time + +Just now → 1 sec ago → 5 sec ago → 1 min ago → 5 min ago → 1 hour ago → 5 hours ago → 1 day ago → 5 days ago → This week → Last week → 2 weeks → 1 month ago → 5 months ago → 1 year ago → 5 years ago + +### For constrained space + +{1}s   {1}m   {1}h   {1}d   {1}wk   {1}mo   {1}yr + +## File extensions + +Use uppercase and no period in: + +- buttons +- checkboxes +- radio buttons +- menu items + + + + + + +Use lowercase and specify a noun in full sentences in: + +- messages +- notices +- tooltips + + + + + diff --git a/website/docs/content/lists/lists.md b/website/docs/content/lists/lists.md index a06cd19084..52b1ebe569 100644 --- a/website/docs/content/lists/lists.md +++ b/website/docs/content/lists/lists.md @@ -1,3 +1,24 @@ --- title: Lists --- + +Rules for punctuation, capitalization, and structure. + +## Rules + +- No period in bulleted lists and lists with icons. (But: if there's more than one sentence in a bullet — make all bullets end with periods.) +- No period in numbered lists. +- Use sentence case capitalization. +- Use numbered lists for a sequence of actions. +- Use parallel structure in lists. + + + + + diff --git a/website/docs/content/modals/modals.md b/website/docs/content/modals/modals.md index 943a329bda..6ad28b4273 100644 --- a/website/docs/content/modals/modals.md +++ b/website/docs/content/modals/modals.md @@ -1,3 +1,45 @@ --- title: Modals --- + +Every modal should read as a single coherent thought — title, body, and button connected into one sentence. + +## The rule + +Treat a modal window (or any kind of window) as a single "sentence." It makes it easier for you to follow a structure, and easier for everyone else to see patterns and follow them. Every full sentence has a subject (usually a title), a predicate (a button), and everything in between that describes the subject or features of the subject. + +## Simple modals + +A simple modal is a short "sentence." It only contains a title, a body, and one or several buttons. + +- Never start with "Are you sure" — get straight to the point. +- Don't replace action words or terms with synonyms. + + + + + + + + + + + +## Complex windows + +Complex windows are longer "sentences." Apply the same rules as for a simple modal, plus use the same wording pattern for the same elements. + +Good example: + +- (checkbox) Remove competitor mentions +- (checkbox) Send a copy to the team +- (switch) AI Summary +- (switch) Regular update diff --git a/website/docs/content/onboarding/onboarding.md b/website/docs/content/onboarding/onboarding.md index f0945361ff..07b66420b5 100644 --- a/website/docs/content/onboarding/onboarding.md +++ b/website/docs/content/onboarding/onboarding.md @@ -1,3 +1,45 @@ --- title: Onboarding --- + +Writing guidance for welcome flows, setup screens, and what's new announcements. + +## Voice + +**Voltage: medium-high** + +It's appropriate to speak more boldly using a higher voltage. The goal is to create a pleasant anticipation of something new and useful to the user. Keep the tone encouraging but task-focused. Use active verbs with forward momentum — track, launch, explore, connect, map. Avoid "is now available" or "has been added." + +When writing an onboarding or what's new message, think about: + +- Who are your target users? Are they beginners or advanced? +- What's their goal? +- Can they understand what you say? Can they remember everything you say? + +## Onboarding example + + + + + + +## What's new example + + + + + diff --git a/website/docs/content/placeholders/placeholders.md b/website/docs/content/placeholders/placeholders.md index 151cfdaf3a..5b39781b6f 100644 --- a/website/docs/content/placeholders/placeholders.md +++ b/website/docs/content/placeholders/placeholders.md @@ -1,3 +1,30 @@ --- title: Placeholders --- + +A placeholder's job is to hint, not to instruct. + +## Rules + +The role of a placeholder is to provide a hint. A good placeholder: + +- Complements the label +- Clarifies what needs to be entered +- Provides an accurate example + + + + + + +## Usage + +- For email and domain placeholders, use example@mail.com and https://example.com. +- Omit articles in placeholders that act like additional info or short instruction, not full sentences. +- In rare cases where placeholders include full sentences or more than 1 sentence, use articles. diff --git a/website/docs/content/pricing-and-sales/pricing-and-sales.md b/website/docs/content/pricing-and-sales/pricing-and-sales.md index 1e11b2fce4..052c62fc62 100644 --- a/website/docs/content/pricing-and-sales/pricing-and-sales.md +++ b/website/docs/content/pricing-and-sales/pricing-and-sales.md @@ -1,3 +1,52 @@ --- title: Pricing and sales --- + +How to write for upgrade prompts, limits, and subscription changes. + +## Voice + +**Voltage: medium-high to medium** + +Usually, this type of message prevents users from doing what they do, and they're not happy about it. The goal is to help them see why they need an upgrade. You can apply a higher voltage, but use it cautiously and consider your context. Never say "upgrade to get access to more features" — explain the benefits instead. + +## Upsell, limits, downgrade + +### Upsell + + + + + + +Good example: Your first 7 days are on us. Then $X/mo. + +### Limits + + + + + + +### Downgrade + + + + + diff --git a/website/docs/content/system-states/system-states.md b/website/docs/content/system-states/system-states.md index 34bef26170..ec2a978922 100644 --- a/website/docs/content/system-states/system-states.md +++ b/website/docs/content/system-states/system-states.md @@ -1,3 +1,69 @@ --- title: System states --- + +How to write for empty, loading, success, and failed states — each with its own voltage. + +## Empty + +**Voltage: medium** + +An empty state is a great place to nudge users toward a desired action. A simple message like "Nothing here yet" could be a missed opportunity to engage the user. + +- In the title, announce the state or say what to do. +- Say how the action will benefit the user. +- Don't say anything about any other steps inside the flow or after. + + + + + + +## Loading + +**Voltage: medium** + +It's quite a flexible state in terms of what you can say. Use the brand voice to make the interaction friendly (for simple actions), exciting or calming (if some major action requires waiting). Remember to stay clear and useful. + + + + + + +## Success + +**Voltage: medium-high** + +You can express some excitement or congratulate the user on a completed action or a milestone. Say what's now available to them or what they can do next. Try not to just state a bland fact, but if you are, use a simple tense and active voice. + + + + + + +## Failed + +**Voltage: low** + +A failed state is closely related to an error. You can use most principles of writing an error message when writing a failed state. + + + + + diff --git a/website/docs/content/voice-and-style/voice-and-style.md b/website/docs/content/voice-and-style/voice-and-style.md index 635e1467ca..1fed1a1f4e 100644 --- a/website/docs/content/voice-and-style/voice-and-style.md +++ b/website/docs/content/voice-and-style/voice-and-style.md @@ -1,3 +1,319 @@ --- title: Voice and style --- + +## Brand voice in product + +Master brand voice is a starting point for multiple channels. It can be referenced for high-energy moments in user flows. See the [Brand Voice](https://drive.google.com/drive/folders/15d-wIWEK7qL5fE6ny_ruNJA_Kda9MPDo) and the [style guide](https://drive.google.com/file/d/1azSeVQYlCIPVummxjLE18e1vydBgnHOl/view?usp=drive_link). + +The master brand voice is bold and energetic — but it's a starting point, not a fixed register. Just like a person speaks differently depending on the situation, the brand also adjusts how it speaks. User experience has many moments and each should use its own tone: happy and cheerful for celebration or empathetic for something like changes in pricing. + +Voice varies depending on a pattern: + +| UX pattern | Voice voltage | +| --- | --- | +| Onboarding and what's new | Medium-high | +| Pricing, sales | Medium-high to medium | +| Feedback | Medium | +| System states (success, loading, failed) | Medium-high to low | +| Warnings | Medium-low to low | +| Errors | Low | + +## Capitalization + +Use sentence case by default for all elements. It's easier to read and is more natural and approachable. + +Only use title case for: + +- Page titles (H1) +- Table titles +- Graph titles +- Widget titles +- Chart legends and axis descriptions +- Tabs +- Pills + +### Words to capitalize + +- Proper nouns +- First word of a title or subtitle +- Nouns, verbs, adjectives, adverbs, pronouns +- First word after a colon or em dash in a heading +- Second part of hyphenated major words: Award-Winning +- Second part of phrasal verbs: Sign Up + +### Words NOT to capitalize + +- Articles: the, a, an +- Prepositions (under 4 letters): for, with, to, in, on, at +- Conjunctions: and, or, but +- "To" in an infinitive + +### Semrush product names + +Capitalize the full name when referring to a specific Semrush tool. Use lowercase when referring to the functionality generically. + + + + + + +### "Toolkit" + +Capitalize "Toolkit" only when it's part of an official product name. Otherwise use lowercase. + + + + + + +### "Report" and "tool" + +Do not capitalize "report" or "tool" unless they are part of an official product name. + + + + + + +| Element | Case | +| --- | --- | +| Page titles | Title case | +| Table / graph / widget titles | Title case | +| Chart legends and axes | Title case | +| Tabs and pills | Title case | +| Modal titles | Sentence case | +| Notice titles | Sentence case | +| Buttons | Sentence case | +| Field labels | Sentence case | +| Checkboxes | Sentence case | +| Menus and dropdowns | Sentence case | +| Tags | Sentence case | +| Links | Sentence case | +| Lists | Sentence case | +| Filter names | Sentence case | + +## Punctuation and special symbols + +### Oxford commas + +Always use the Oxford comma, or serial comma, for a series of items. + + + + + + +### Periods + +If your text is a full sentence, add a period. If it's a short, direct phrase — don't. Also use it with shortened forms of words (mainly in table columns) and include in quotation marks and brackets. + +Omit in: + +- headings +- lists (but: if there's more than one sentence in a bullet — make all bullets end with a punctuation mark) +- placeholders +- checkboxes +- lists with bullets and icons +- tooltips that serve as labels for icons or display the element's full name +- after URLs (not text links) +- lines above and below input fields +- "clean" designs where there are no other elements with periods +- buttons + + + + + + +### Semicolons + +Don't use semicolons (**;**). They add a formal, academic tone and negatively affect user comprehension in UX writing. Use periods, commas, or em dashes instead. + +### Colons + +Use colons to offset a list or to join two closely related phrases. If a complete sentence follows a colon, capitalize the first word. + +Good examples: + +- We'll cover three topics: market changes, ecommerce strategy, and AI fundamentals. +- To rank well, you must follow best practices: Content quality is critical. + +### Quotation marks + +Only use them when quoting someone's words or referring to a file or asset name. Use curly ("") marks. Don't use quotes when directly referring to interface elements. + + + + + + +### Apostrophe + +| Symbol | HTML code | Windows shortcut | MacOS shortcut | +| --- | --- | --- | --- | +| ' | `’` | Alt + 0146 | ⌥ ⇧ ] | + +Use the curly style, just like for the quotation marks. + + + + + + +### Em dashes + +Use sparingly in place of a comma or colon. Include a space before and after the em dash. + + + + + + +### Parentheses + +The only acceptable use of parentheses in UI elements is short supplementary information. To decide whether the information is supplementary or primary, read your text without the part in the parentheses. If it loses its original meaning, the information you consider additional is in fact primary and it should not be in parentheses. If the text keeps the meaning you intend — consider removing the parentheses. + + + + + + +### Ampersand + +Avoid. If there's enough space — always use "and". If used, enclose in spaces. + + + + + + +### Number sign + +Omit the space after the sign. + + + + + + +### Percent sign + +In a column name, use at the end of the name preceded by a space. Omit the space before the percent sign (Exception: German, French, Swedish languages). + + + + + + +### Minus and plus signs + +| Symbol | HTML entity | +| --- | --- | +| − | `−` | +| + | `+` | + +- Omit the spaces between the sign and a numeric value. +- Use to show changes in metrics. +- If you can't use the minus character for some reason, use the en dash. + + + + + + +### Slash + +Omit the spaces around the sign. + + + + + + +### Multiplication sign + +Avoid using the "x" letter. + + + + + + +## Emojis + +Don't use emojis in UI. Never replace words with emojis. diff --git a/website/docs/content/warnings/warnings.md b/website/docs/content/warnings/warnings.md index 7db2e87909..0212283e88 100644 --- a/website/docs/content/warnings/warnings.md +++ b/website/docs/content/warnings/warnings.md @@ -1,3 +1,37 @@ --- title: Warnings --- + +How to write for critical and non-critical warning states. + +## Voice + +**Voltage: low / medium-low** + +Always stick to the point, speak like an expert, but stay approachable. For critical warnings, always lead with what will happen and when, then give the user a clear path forward. Non-critical warnings don't need urgency. A nudge is enough — acknowledge what changed, and suggest what to do next without pushing. + +## Critical + + + + + + +## Non-critical + + + + + From d3f8e1035967aaabdb37b535c5cba681b780a32e Mon Sep 17 00:00:00 2001 From: Julia Mnizhek Date: Wed, 24 Jun 2026 15:44:40 +0200 Subject: [PATCH 3/6] [docs] move Content to Foundation section --- website/docs/.vitepress/sidebarConfig.ts | 211 +++++++++--------- website/docs/.vitepress/theme/DosDonts.vue | 77 +------ website/docs/.vitepress/theme/style.css | 87 ++++++++ .../content-principles/content-principles.md | 2 + 4 files changed, 207 insertions(+), 170 deletions(-) diff --git a/website/docs/.vitepress/sidebarConfig.ts b/website/docs/.vitepress/sidebarConfig.ts index 9c72c72a31..37ee00574a 100644 --- a/website/docs/.vitepress/sidebarConfig.ts +++ b/website/docs/.vitepress/sidebarConfig.ts @@ -109,121 +109,122 @@ export const sideBarConfig: SidebarConfig = [ }, ], }, - ], - }, - { - text: 'Content', - items: [ - { - link: '/content/content-principles/content-principles', - activeMatch: '/content/content-principles/', - text: 'Content principles', - }, - { - text: 'Style & grammar', - collapsed: true, - items: [ - { - link: '/content/voice-and-style/voice-and-style', - activeMatch: '/content/voice-and-style/', - text: 'Voice and style', - }, - { - link: '/content/grammar/grammar', - activeMatch: '/content/grammar/', - text: 'Grammar', - }, - { - link: '/content/capitalization/capitalization', - activeMatch: '/content/capitalization/', - text: 'Capitalization', - }, - { - link: '/content/date-format/date-format', - activeMatch: '/content/date-format/', - text: 'Date format', - }, - { - link: '/content/file-extensions/file-extensions', - activeMatch: '/content/file-extensions/', - text: 'File extensions', - }, - { - link: '/content/numbers/numbers', - activeMatch: '/content/numbers/', - text: 'Numbers', - }, - { - link: '/content/punctuation/punctuation', - activeMatch: '/content/punctuation/', - text: 'Punctuation and special symbols', - }, - { - link: '/content/units-of-measurement/units-of-measurement', - activeMatch: '/content/units-of-measurement/', - text: 'Units of measurement', - }, - ], - }, { - text: 'UX patterns', + text: 'Content', collapsed: true, items: [ { - link: '/content/onboarding/onboarding', - activeMatch: '/content/onboarding/', - text: 'Onboarding', - }, - { - link: '/content/pricing-and-sales/pricing-and-sales', - activeMatch: '/content/pricing-and-sales/', - text: 'Pricing and sales', - }, - { - link: '/content/feedback/feedback', - activeMatch: '/content/feedback/', - text: 'Feedback', - }, - { - link: '/content/system-states/system-states', - activeMatch: '/content/system-states/', - text: 'System states', - }, - { - link: '/content/warnings/warnings', - activeMatch: '/content/warnings/', - text: 'Warnings', + link: '/content/content-principles/content-principles', + activeMatch: '/content/content-principles/', + text: 'Content principles', }, { - link: '/content/errors/errors', - activeMatch: '/content/errors/', - text: 'Errors', - }, - { - link: '/content/lists/lists', - activeMatch: '/content/lists/', - text: 'Lists', - }, - { - link: '/content/modals/modals', - activeMatch: '/content/modals/', - text: 'Modals', + text: 'Style & grammar', + collapsed: true, + items: [ + { + link: '/content/voice-and-style/voice-and-style', + activeMatch: '/content/voice-and-style/', + text: 'Voice and style', + }, + { + link: '/content/grammar/grammar', + activeMatch: '/content/grammar/', + text: 'Grammar', + }, + { + link: '/content/capitalization/capitalization', + activeMatch: '/content/capitalization/', + text: 'Capitalization', + }, + { + link: '/content/date-format/date-format', + activeMatch: '/content/date-format/', + text: 'Date format', + }, + { + link: '/content/file-extensions/file-extensions', + activeMatch: '/content/file-extensions/', + text: 'File extensions', + }, + { + link: '/content/numbers/numbers', + activeMatch: '/content/numbers/', + text: 'Numbers', + }, + { + link: '/content/punctuation/punctuation', + activeMatch: '/content/punctuation/', + text: 'Punctuation and special symbols', + }, + { + link: '/content/units-of-measurement/units-of-measurement', + activeMatch: '/content/units-of-measurement/', + text: 'Units of measurement', + }, + ], }, - ], - }, - { - text: 'UI elements', - collapsed: true, - items: [ { - link: '/content/placeholders/placeholders', - activeMatch: '/content/placeholders/', - text: 'Placeholders', + text: 'UX patterns', + collapsed: true, + items: [ + { + link: '/content/onboarding/onboarding', + activeMatch: '/content/onboarding/', + text: 'Onboarding', + }, + { + link: '/content/pricing-and-sales/pricing-and-sales', + activeMatch: '/content/pricing-and-sales/', + text: 'Pricing and sales', + }, + { + link: '/content/feedback/feedback', + activeMatch: '/content/feedback/', + text: 'Feedback', + }, + { + link: '/content/system-states/system-states', + activeMatch: '/content/system-states/', + text: 'System states', + }, + { + link: '/content/warnings/warnings', + activeMatch: '/content/warnings/', + text: 'Warnings', + }, + { + link: '/content/errors/errors', + activeMatch: '/content/errors/', + text: 'Errors', + }, + { + link: '/content/lists/lists', + activeMatch: '/content/lists/', + text: 'Lists', + }, + { + link: '/content/modals/modals', + activeMatch: '/content/modals/', + text: 'Modals', + }, + ], }, { - link: '/content/buttons/buttons', - activeMatch: '/content/buttons/', - text: 'Buttons', + text: 'UI elements', + collapsed: true, + items: [ + { + link: '/content/placeholders/placeholders', + activeMatch: '/content/placeholders/', + text: 'Placeholders', + }, + { + link: '/content/buttons/buttons', + activeMatch: '/content/buttons/', + text: 'Buttons', + }, + ], }, ], }, diff --git a/website/docs/.vitepress/theme/DosDonts.vue b/website/docs/.vitepress/theme/DosDonts.vue index f09e006e5c..818fa09054 100644 --- a/website/docs/.vitepress/theme/DosDonts.vue +++ b/website/docs/.vitepress/theme/DosDonts.vue @@ -1,81 +1,28 @@ - - \ No newline at end of file diff --git a/website/docs/.vitepress/theme/style.css b/website/docs/.vitepress/theme/style.css index 399a0b4e5e..72524fbc6c 100644 --- a/website/docs/.vitepress/theme/style.css +++ b/website/docs/.vitepress/theme/style.css @@ -1197,3 +1197,90 @@ h6[class] { .vp-doc li[data-ui-name]+li[data-ui-name] { margin-top: 2px; } + +/* DosDonts component */ +.vp-doc table.dosdonts { + display: table; + width: 100%; + max-width: 100%; + table-layout: fixed; + border-collapse: separate; + border-spacing: 0; + margin: 20px 0 40px; + border-radius: var(--intergalactic-surface-rounded, 6px); + padding-top: var(--intergalactic-spacing-4x, 16px); + padding-bottom: var(--intergalactic-spacing-4x, 16px); + background: var(--intergalactic-bg-secondary-neutral, #f4f5f9); + overflow: hidden; +} + +.vp-doc table.dosdonts tr { + border-bottom: none; + background: transparent; +} + +.vp-doc table.dosdonts tr:hover, +.vp-doc table.dosdonts tbody tr:hover, +.dark .vp-doc table.dosdonts tr:hover, +.dark .vp-doc table.dosdonts tbody tr:hover { + background: transparent; +} + +.vp-doc table.dosdonts th, +.vp-doc table.dosdonts td { + width: 50%; + box-sizing: border-box; + vertical-align: middle; + text-align: center; + border: none; +} + +.vp-doc table.dosdonts th { + padding: 0 var(--intergalactic-spacing-10x, 40px) var(--intergalactic-spacing-2x, 8px); + font-size: var(--intergalactic-fs-400, 20px); + line-height: var(--intergalactic-lh-400, 120%); + font-weight: var(--intergalactic-bold, 700); + background: var(--intergalactic-bg-secondary-neutral, #f4f5f9); +} + +.vp-doc table.dosdonts th:first-child, +.vp-doc table.dosdonts td:first-child { + border-right: 1px solid var(--intergalactic-border-secondary, #e0e1e9); +} + +.vp-doc table.dosdonts th:first-child { + color: var(--intergalactic-text-critical, #d1002f); +} + +.vp-doc table.dosdonts th:last-child { + color: var(--intergalactic-text-success, #007c65); +} + +.vp-doc table.dosdonts td { + padding: 0; + font-size: var(--intergalactic-fs-200, 14px); + line-height: var(--intergalactic-lh-200, 142%); +} + +.vp-doc table.dosdonts .dosdonts-cell { + padding: var(--intergalactic-spacing-6x, 24px) var(--intergalactic-spacing-10x, 40px); + text-align: center; + word-wrap: break-word; + overflow-wrap: break-word; +} + +.vp-doc table.dosdonts .dosdonts-cell > * { + width: 100%; + max-width: 100%; + text-align: center; +} + +.vp-doc table.dosdonts .dosdonts-cell p { + margin-top: 0; + margin-bottom: var(--intergalactic-spacing-2x, 8px); +} + +.vp-doc table.dosdonts .dosdonts-cell p:last-child { + margin-bottom: 0; +} + diff --git a/website/docs/content/content-principles/content-principles.md b/website/docs/content/content-principles/content-principles.md index 922d0a350b..d9753902c4 100644 --- a/website/docs/content/content-principles/content-principles.md +++ b/website/docs/content/content-principles/content-principles.md @@ -189,7 +189,9 @@ It's okay to use a full version if you want to highlight an action: Writing for a 6th-grade reading level on the Flesch-Kincaid readability scale includes more people. Write with short sentences, use simpler nouns, avoid adverbs and adjectives unless they carry real meaning. Use simple verb tenses (past, present, future) and active voice. +::: tip You can check readability using [hemingwayapp.com](https://hemingwayapp.com/). +::: ## Consistency From 718c96e177e519cd146097042247a2f014edde98 Mon Sep 17 00:00:00 2001 From: Julia Mnizhek Date: Thu, 25 Jun 2026 13:42:03 +0200 Subject: [PATCH 4/6] [docs] update styles --- website/docs/.vitepress/theme/DosDonts.vue | 91 +++++++++++++++++++++- website/docs/.vitepress/theme/style.css | 86 -------------------- 2 files changed, 87 insertions(+), 90 deletions(-) diff --git a/website/docs/.vitepress/theme/DosDonts.vue b/website/docs/.vitepress/theme/DosDonts.vue index 818fa09054..03df3c4f81 100644 --- a/website/docs/.vitepress/theme/DosDonts.vue +++ b/website/docs/.vitepress/theme/DosDonts.vue @@ -1,9 +1,5 @@ + + diff --git a/website/docs/.vitepress/theme/style.css b/website/docs/.vitepress/theme/style.css index 72524fbc6c..1c05cb8b12 100644 --- a/website/docs/.vitepress/theme/style.css +++ b/website/docs/.vitepress/theme/style.css @@ -1198,89 +1198,3 @@ h6[class] { margin-top: 2px; } -/* DosDonts component */ -.vp-doc table.dosdonts { - display: table; - width: 100%; - max-width: 100%; - table-layout: fixed; - border-collapse: separate; - border-spacing: 0; - margin: 20px 0 40px; - border-radius: var(--intergalactic-surface-rounded, 6px); - padding-top: var(--intergalactic-spacing-4x, 16px); - padding-bottom: var(--intergalactic-spacing-4x, 16px); - background: var(--intergalactic-bg-secondary-neutral, #f4f5f9); - overflow: hidden; -} - -.vp-doc table.dosdonts tr { - border-bottom: none; - background: transparent; -} - -.vp-doc table.dosdonts tr:hover, -.vp-doc table.dosdonts tbody tr:hover, -.dark .vp-doc table.dosdonts tr:hover, -.dark .vp-doc table.dosdonts tbody tr:hover { - background: transparent; -} - -.vp-doc table.dosdonts th, -.vp-doc table.dosdonts td { - width: 50%; - box-sizing: border-box; - vertical-align: middle; - text-align: center; - border: none; -} - -.vp-doc table.dosdonts th { - padding: 0 var(--intergalactic-spacing-10x, 40px) var(--intergalactic-spacing-2x, 8px); - font-size: var(--intergalactic-fs-400, 20px); - line-height: var(--intergalactic-lh-400, 120%); - font-weight: var(--intergalactic-bold, 700); - background: var(--intergalactic-bg-secondary-neutral, #f4f5f9); -} - -.vp-doc table.dosdonts th:first-child, -.vp-doc table.dosdonts td:first-child { - border-right: 1px solid var(--intergalactic-border-secondary, #e0e1e9); -} - -.vp-doc table.dosdonts th:first-child { - color: var(--intergalactic-text-critical, #d1002f); -} - -.vp-doc table.dosdonts th:last-child { - color: var(--intergalactic-text-success, #007c65); -} - -.vp-doc table.dosdonts td { - padding: 0; - font-size: var(--intergalactic-fs-200, 14px); - line-height: var(--intergalactic-lh-200, 142%); -} - -.vp-doc table.dosdonts .dosdonts-cell { - padding: var(--intergalactic-spacing-6x, 24px) var(--intergalactic-spacing-10x, 40px); - text-align: center; - word-wrap: break-word; - overflow-wrap: break-word; -} - -.vp-doc table.dosdonts .dosdonts-cell > * { - width: 100%; - max-width: 100%; - text-align: center; -} - -.vp-doc table.dosdonts .dosdonts-cell p { - margin-top: 0; - margin-bottom: var(--intergalactic-spacing-2x, 8px); -} - -.vp-doc table.dosdonts .dosdonts-cell p:last-child { - margin-bottom: 0; -} - From dd201508dc105d22186e5e2229d36b96bd2c9319 Mon Sep 17 00:00:00 2001 From: Julia Mnizhek Date: Mon, 6 Jul 2026 20:39:57 +0200 Subject: [PATCH 5/6] [docs] updates for Content section --- website/docs/.vitepress/theme/DosDonts.vue | 23 +-- .../docs/.vitepress/theme/DosDontsCopy.vue | 141 ++++++++++++++++++ website/docs/.vitepress/theme/index.ts | 2 + website/docs/content/buttons/buttons.md | 8 +- .../content/capitalization/capitalization.md | 52 +++---- .../content-principles/content-principles.md | 76 +++++----- website/docs/content/errors/errors.md | 20 +-- website/docs/content/feedback/feedback.md | 4 +- .../file-extensions/file-extensions.md | 12 +- website/docs/content/grammar/grammar.md | 28 ++-- website/docs/content/lists/lists.md | 4 +- website/docs/content/modals/modals.md | 8 +- website/docs/content/numbers/numbers.md | 20 +-- website/docs/content/onboarding/onboarding.md | 8 +- .../docs/content/placeholders/placeholders.md | 4 +- .../pricing-and-sales/pricing-and-sales.md | 16 +- .../docs/content/punctuation/punctuation.md | 72 ++++----- .../content/system-states/system-states.md | 16 +- .../units-of-measurement.md | 4 +- .../voice-and-style/voice-and-style.md | 60 ++++---- website/docs/content/warnings/warnings.md | 8 +- 21 files changed, 360 insertions(+), 226 deletions(-) create mode 100644 website/docs/.vitepress/theme/DosDontsCopy.vue diff --git a/website/docs/.vitepress/theme/DosDonts.vue b/website/docs/.vitepress/theme/DosDonts.vue index 03df3c4f81..8665b82f83 100644 --- a/website/docs/.vitepress/theme/DosDonts.vue +++ b/website/docs/.vitepress/theme/DosDonts.vue @@ -2,21 +2,17 @@ - + @@ -82,30 +78,25 @@ } .vp-doc table.dosdonts td { - padding: 0; + padding: var(--intergalactic-spacing-6x, 24px) var(--intergalactic-spacing-10x, 40px); font-size: var(--intergalactic-fs-200, 14px); line-height: var(--intergalactic-lh-200, 142%); -} - -.vp-doc table.dosdonts .dosdonts-cell { - padding: var(--intergalactic-spacing-6x, 24px) var(--intergalactic-spacing-10x, 40px); - text-align: center; word-wrap: break-word; overflow-wrap: break-word; } -.vp-doc table.dosdonts .dosdonts-cell > * { +.vp-doc table.dosdonts td > * { width: 100%; max-width: 100%; text-align: center; } -.vp-doc table.dosdonts .dosdonts-cell p { +.vp-doc table.dosdonts td p { margin-top: 0; margin-bottom: var(--intergalactic-spacing-2x, 8px); } -.vp-doc table.dosdonts .dosdonts-cell p:last-child { +.vp-doc table.dosdonts td p:last-child { margin-bottom: 0; } diff --git a/website/docs/.vitepress/theme/DosDontsCopy.vue b/website/docs/.vitepress/theme/DosDontsCopy.vue new file mode 100644 index 0000000000..dfd4ed5d92 --- /dev/null +++ b/website/docs/.vitepress/theme/DosDontsCopy.vue @@ -0,0 +1,141 @@ + + + diff --git a/website/docs/.vitepress/theme/index.ts b/website/docs/.vitepress/theme/index.ts index d34494d0db..de190d691f 100644 --- a/website/docs/.vitepress/theme/index.ts +++ b/website/docs/.vitepress/theme/index.ts @@ -8,6 +8,7 @@ import { h, onMounted, watch, nextTick } from 'vue'; import DevportalLogo from './DevportalLogo.vue'; import DocFooter from './DocFooter.vue'; import DosDonts from './DosDonts.vue'; +import DosDontsCopy from './DosDontsCopy.vue'; import LegacyEmailsView from './LegacyEmailsView.vue'; import Page404 from './Page404.vue'; import PageTopTabs from './PageTopTabs.vue'; @@ -31,6 +32,7 @@ export default { app.component('LegacyEmailsView', LegacyEmailsView); app.component('TypesView', TypesView); app.component('DosDonts', DosDonts); + app.component('DosDontsCopy', DosDontsCopy); app.component('Playground', Playground); }, setup() { diff --git a/website/docs/content/buttons/buttons.md b/website/docs/content/buttons/buttons.md index a6ba4c30e6..f94b90a6ed 100644 --- a/website/docs/content/buttons/buttons.md +++ b/website/docs/content/buttons/buttons.md @@ -19,14 +19,14 @@ The button should feel like a start of a new action and kind of a forward motion ALWAYS match the button to the title. - + - + - Mostly use verb + noun format (e.g., "Save document" not just "Save"). Always consider context: it can be "Export all data" if there are multiple options to choose from AND "Export data" when it's just one option. - Clearly indicate the result of clicking the button. @@ -35,14 +35,14 @@ ALWAYS match the button to the title. - Try to keep the text under 3 words. - Avoid vague labels like "Submit" or "Click here". - + - + Good example: Create account (Registration flow — clear outcome for the user) diff --git a/website/docs/content/capitalization/capitalization.md b/website/docs/content/capitalization/capitalization.md index 435efc53cb..3e0522a864 100644 --- a/website/docs/content/capitalization/capitalization.md +++ b/website/docs/content/capitalization/capitalization.md @@ -14,23 +14,23 @@ With this type of case, all words are capitalized, except for minor words that a * Tabs * Pills - + - + - + - + ### Words to capitalize * Major words: nouns, verbs, adjectives, adverbs, pronouns, and all words of 4 letters or more @@ -47,7 +47,7 @@ With this type of case, all words are capitalized, except for minor words that a * “To” in an infinitive * “Report” and “tool” if they aren't part of the title - + - + ## Sentence case With this type of case, most words in a titles or headings are in lowercase. You should capitalize only: @@ -75,96 +75,96 @@ With this type of case, most words in a titles or headings are in lowercase. You * Modal window titles - + - + * Notice titles - + - + * Buttons - + - + * Field labels * Checkboxes - + - + * Menus * Dropdown items - + - + * Tags - + - + * Links - + - + * Bulleted and numbered lists - + - + * Filter names (including filters in the report headers) * Company business units (Marketing department, R&D unit) diff --git a/website/docs/content/content-principles/content-principles.md b/website/docs/content/content-principles/content-principles.md index d9753902c4..70206853f5 100644 --- a/website/docs/content/content-principles/content-principles.md +++ b/website/docs/content/content-principles/content-principles.md @@ -6,36 +6,36 @@ title: Content principles People don't care about your 50th new cool feature. They want their task complete as quickly and easily as possible. All writing must prioritize user goals and comprehension over business jargon or marketing speak. - + - + Eliminate "feature-speak". Always make sure the texts show benefit for the user. - + - + Cut corporate filler — phrases that exist to sound official rather than communicate something. In the context of web content and quick scanning you don't sound polite, you sound annoying. - + - + ## Write for scannability @@ -45,14 +45,14 @@ People on the internet don't read like they read books. They scan, usually in th - Keep sentences under 20 words when possible. If you need to take a breath to finish reading the sentence out loud — it's a bad sign. - Have one idea per sentence, split complex thoughts. - + - + - Use actionable language. Every button, link, and CTA must clearly indicate what happens when clicked. Never say "Click here". @@ -60,7 +60,7 @@ Good examples: Save draft, Publish article, Delete account. **Got it** — Exception. Use only for dismissible informational modals where no critical action is taken and the user is simply acknowledging they've read the information. - + - + - Avoid passive voice unless the action is product-side. - + @@ -115,23 +115,23 @@ Good examples: Save draft, Publish article, Delete account.

The report owner deleted the report.

The report expired and has been deleted.

- + - Naturally connect texts within one UI element — the title, body, and button should form one coherent thought. - + - + - Cut unnecessary adverbs ("successfully") or those that reflect a writer's opinion ("quickly", "easily"). - Use parallel structure in lists. - + - + - DO NOT break semantic blocks. Keep related information together. - + - + ## Conversational writing @@ -159,14 +159,14 @@ Write in a way a person talks to another person, not a system. - Use contractions — they reduce formality without reducing clarity. Be mindful of how many contractions you use in a sentence. Too many contractions can make things difficult to read. - + - + It's okay to use a full version if you want to highlight an action: @@ -174,14 +174,14 @@ It's okay to use a full version if you want to highlight an action: - Read your text aloud. If it sounds unnatural spoken, rewrite it. Passive, overly formal, or instruction-heavy sentences fail this test immediately. - + - + - Match the emotional register of the moment. Conversational doesn't mean casual. An error moment calls for calm and direct tone, a success moment can be warmer. @@ -235,14 +235,14 @@ If your content will be localized, consider the following: - When adding variables into text, remember that languages have different structures. What looks okay in UI in English can simply not work in another language. - Try to use gender-neutral language. - + - + - (For frontend) Don't break one sentence into several parts: word order in many languages does not match word order in English. @@ -259,7 +259,7 @@ Add alt text only if the image brings additional value to the rest of the conten - Use sentence case - Capitalize proper nouns - + @@ -267,7 +267,7 @@ Add alt text only if the image brings additional value to the rest of the conten

alt="Black Converse canvas shoe"

alt="Black Converse canvas shoe with white laces on a white background"

- + ### Age @@ -304,33 +304,33 @@ Define a word in simple and familiar terms. A definition should not make the rea ### DO NOT use the same term to define a term - + - + ### When referencing another term, use the term itself, not its definition - + - + ### A definition of a noun term cannot be a verb - + - + diff --git a/website/docs/content/errors/errors.md b/website/docs/content/errors/errors.md index abd6723281..b49345ffd0 100644 --- a/website/docs/content/errors/errors.md +++ b/website/docs/content/errors/errors.md @@ -20,20 +20,20 @@ Regardless of the design component or message length, the most comprehensive err This should be the first part of the message, like in a headline (if the UI element allows). Be sure to communicate the general outcome of the error. Use plain language and focus on what it means to the user. - + - + ### The cause It's helpful to have an explanation of why something happened — it can increase the user's understanding of the issue. - + - + ### How to fix it This part tells the user what they can do about it. Offer a step-by-step resolution in the most simple and actionable way. If there's nothing for them to do, then explain what the product is doing. Offer a path forward within the error state itself, such as a "Try again" or "Go back" button. Linking to a help article can be useful, but only if that article is specific and descriptive to the error's use case. - + - + ## Main principles @@ -92,22 +92,22 @@ Use "please" and "sorry" only when: ### Critical - + - + ### Non-critical - + - + diff --git a/website/docs/content/feedback/feedback.md b/website/docs/content/feedback/feedback.md index c6a61cfa4e..3c0ffd6bf4 100644 --- a/website/docs/content/feedback/feedback.md +++ b/website/docs/content/feedback/feedback.md @@ -10,7 +10,7 @@ How to ask users for their opinion without sounding like a survey form. Move away from formal wording that feels lifeless. Keep it simple and friendly — write like a person, not a system. Avoid survey-speak ("evaluate," "rate your experience") in favor of plain, human phrasing. - + - + diff --git a/website/docs/content/file-extensions/file-extensions.md b/website/docs/content/file-extensions/file-extensions.md index 3e13c0fb13..09886c51bf 100644 --- a/website/docs/content/file-extensions/file-extensions.md +++ b/website/docs/content/file-extensions/file-extensions.md @@ -8,23 +8,23 @@ Use uppercase and no period in: * radio buttons * menu items - + - + Use lowercase and specify a noun after the extension in **full sentences** in: * tooltips * notices * messages - + - + diff --git a/website/docs/content/grammar/grammar.md b/website/docs/content/grammar/grammar.md index 00ea2370fc..84a342d1b2 100644 --- a/website/docs/content/grammar/grammar.md +++ b/website/docs/content/grammar/grammar.md @@ -31,33 +31,33 @@ Use active voice in most cases and use passive voice sparingly. In an active sentence, it's clear who's doing what. The actor is the subject, and the subject of the sentence is doing something. - + - + ### Passive voice At times, active voice can sound too harshly or keep focus on something that's less important in the context. In these cases, switch to passive voice. This separates the actor from the action to soften a sentence. - + - + ### Avoid passive voice by reframing the focus You can usually reframe a message to focus on the object, or on the actions someone could take, as another way to avoid passive voice. - + - + ## Spelling @@ -95,14 +95,14 @@ Use first person (me, I, my) only in these situations: - When additional sensitivity is necessary, or to indicate privacy. - When there's a legal need to use first person to ask for consent. - + - + Sometimes it's okay to use "we" or "us" to mean "Semrush": @@ -167,14 +167,14 @@ Good example: We saw a large traffic spike in January 2023. - Do not add ordinals (st, th, nd) to dates. - + - + ### Time @@ -208,14 +208,14 @@ Use uppercase and no period in: - radio buttons - menu items - + - + Use lowercase and specify a noun in full sentences in: @@ -223,11 +223,11 @@ Use lowercase and specify a noun in full sentences in: - notices - tooltips - + - + diff --git a/website/docs/content/lists/lists.md b/website/docs/content/lists/lists.md index 52b1ebe569..8c11c44751 100644 --- a/website/docs/content/lists/lists.md +++ b/website/docs/content/lists/lists.md @@ -12,7 +12,7 @@ Rules for punctuation, capitalization, and structure. - Use numbered lists for a sequence of actions. - Use parallel structure in lists. - + - + diff --git a/website/docs/content/modals/modals.md b/website/docs/content/modals/modals.md index 6ad28b4273..1a66935aad 100644 --- a/website/docs/content/modals/modals.md +++ b/website/docs/content/modals/modals.md @@ -15,23 +15,23 @@ A simple modal is a short "sentence." It only contains a title, a body, and one - Never start with "Are you sure" — get straight to the point. - Don't replace action words or terms with synonyms. - + - + - + - + ## Complex windows diff --git a/website/docs/content/numbers/numbers.md b/website/docs/content/numbers/numbers.md index 8d39faa84c..c912039f89 100644 --- a/website/docs/content/numbers/numbers.md +++ b/website/docs/content/numbers/numbers.md @@ -4,7 +4,7 @@ title: Numbers For numbers with 4 or more digits, use commas between every 3 digits. - + - + For decimals, use dots. - + - + For a range of numbers, use the [en dash](../punctuation/punctuation.md#en-dash). - + - + For a range with a number sign (#), omit space. - + - + When a number is used as an adjective, use a [hyphen](../punctuation/punctuation.md#hyphen). - + - + diff --git a/website/docs/content/onboarding/onboarding.md b/website/docs/content/onboarding/onboarding.md index 07b66420b5..d4056d56a4 100644 --- a/website/docs/content/onboarding/onboarding.md +++ b/website/docs/content/onboarding/onboarding.md @@ -18,7 +18,7 @@ When writing an onboarding or what's new message, think about: ## Onboarding example - + - + ## What's new example - + - + diff --git a/website/docs/content/placeholders/placeholders.md b/website/docs/content/placeholders/placeholders.md index 5b39781b6f..2595b22e00 100644 --- a/website/docs/content/placeholders/placeholders.md +++ b/website/docs/content/placeholders/placeholders.md @@ -12,7 +12,7 @@ The role of a placeholder is to provide a hint. A good placeholder: - Clarifies what needs to be entered - Provides an accurate example - + - + ## Usage diff --git a/website/docs/content/pricing-and-sales/pricing-and-sales.md b/website/docs/content/pricing-and-sales/pricing-and-sales.md index 052c62fc62..4a5678ec16 100644 --- a/website/docs/content/pricing-and-sales/pricing-and-sales.md +++ b/website/docs/content/pricing-and-sales/pricing-and-sales.md @@ -14,31 +14,31 @@ Usually, this type of message prevents users from doing what they do, and they'r ### Upsell - + - + Good example: Your first 7 days are on us. Then $X/mo. ### Limits - + - + ### Downgrade - + - + diff --git a/website/docs/content/punctuation/punctuation.md b/website/docs/content/punctuation/punctuation.md index d1a457092e..f2d5c09d2e 100644 --- a/website/docs/content/punctuation/punctuation.md +++ b/website/docs/content/punctuation/punctuation.md @@ -13,7 +13,7 @@ title: Punctuation and special symbols * Use sparingly in sentences in place of a comma or colon * Omit the spaces on both sides of the dash - + - + ### En dash @@ -34,7 +34,7 @@ title: Punctuation and special symbols * Use to indicate an empty value in tables * Omit the spaces on both sides of the dash - + - + ### Hyphen @@ -55,7 +55,7 @@ title: Punctuation and special symbols Use for telephone numbers and compound modifiers. - + - + ### Non-breaking hyphen @@ -74,14 +74,14 @@ Use for telephone numbers and compound modifiers. Use to prevent unwanted line breaks. - + - + ### Soft hyphen @@ -92,14 +92,14 @@ Use to prevent unwanted line breaks. * Use to indicate where a hyphenated break is allowed. It’s invisible otherwise * Useful in scenarios when the same string is displayed in different layouts - + - + ## Non-breaking space @@ -109,14 +109,14 @@ Use to prevent unwanted line breaks. Use to keep the words “glued.” - + - + ## Quotation marks and apostrophe @@ -132,7 +132,7 @@ Use to keep the words “glued.” * Dashes, semicolons, exclamation points, and question marks go inside the quotation mark only if they relate to the quotation * Use when quoting UI text, if text formatting isn't available - + - + ### Apostrophe @@ -155,14 +155,14 @@ Use to keep the words “glued.” Use the curly style, just like for the quotation ‘a‘ ’marks - + - + ## Period @@ -170,7 +170,7 @@ Use the curly style, just like for the quotation ‘a‘ ’marks * Include in quotation marks and brackets * Use with shortened forms of words (mainly in table columns) - + - + **Omit:** * in headings @@ -193,18 +193,18 @@ Use the curly style, just like for the quotation ‘a‘ ’marks * in tooltips that serve as labels for icons or display the element’s full name * after URLs - + - + ## Lists @@ -216,7 +216,7 @@ Use the curly style, just like for the quotation ‘a‘ ’marks Use numbered lists for a sequence of actions! ::: - + - + ## Special symbols @@ -238,7 +238,7 @@ Use numbered lists for a sequence of actions! * Enclose in spaces * Avoid. If there’s enough space—always use “and” - + - + ### Number sign @@ -257,14 +257,14 @@ Use numbered lists for a sequence of actions! Omit the space after the sign. - + - + ### Percent sign @@ -276,7 +276,7 @@ Omit the space after the sign. * Omit the space before the percent sign
(**Exception:** German, French, Swedish languages) - + - + ### Minus and plus signs @@ -298,7 +298,7 @@ Omit the space after the sign. * Use to show changes in metrics * If you can't use the minus character for some reason, use the en dash - + - + ### Slash @@ -317,14 +317,14 @@ Omit the space after the sign. Omit the spaces around the sign. - + - + ### Multiplication sign @@ -334,7 +334,7 @@ Omit the spaces around the sign. Avoid using the “x” letter. - +
Don'tDon’t Do
-
- -
+ 		-
- -
+