diff --git a/website/docs/.vitepress/sidebarConfig.ts b/website/docs/.vitepress/sidebarConfig.ts index a5f9562fe8..479fea6a95 100644 --- a/website/docs/.vitepress/sidebarConfig.ts +++ b/website/docs/.vitepress/sidebarConfig.ts @@ -114,34 +114,122 @@ export const sideBarConfig: SidebarConfig = [ collapsed: true, items: [ { - link: '/content/capitalization/capitalization', - activeMatch: '/content/capitalization/', - text: 'Capitalization', + link: '/content/content-principles/content-principles', + activeMatch: '/content/content-principles/', + text: 'Content principles', }, { - 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', + 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', + }, + ], }, { - link: '/content/numbers/numbers', - activeMatch: '/content/numbers/', - text: 'Numbers', + 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/punctuation/punctuation', - activeMatch: '/content/punctuation/', - text: 'Punctuation and special symbols', + text: 'UI elements', + collapsed: true, + items: [ + { + link: '/content/placeholders/placeholders', + activeMatch: '/content/placeholders/', + text: 'Placeholders', + }, + { + link: '/content/buttons/buttons', + activeMatch: '/content/buttons/', + text: 'Buttons', + }, + ], }, { - link: '/content/units-of-measurement/units-of-measurement', - activeMatch: '/content/units-of-measurement/', - text: 'Units of measurement', + link: '/content/glossary/glossary', + activeMatch: '/content/glossary/', + text: 'Glossary', }, ], }, diff --git a/website/docs/.vitepress/theme/DosDonts.vue b/website/docs/.vitepress/theme/DosDonts.vue index f09e006e5c..8665b82f83 100644 --- a/website/docs/.vitepress/theme/DosDonts.vue +++ b/website/docs/.vitepress/theme/DosDonts.vue @@ -2,8 +2,8 @@ - - + + @@ -20,62 +20,83 @@ \ No newline at end of file + 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/GlossaryTable.vue b/website/docs/.vitepress/theme/GlossaryTable.vue new file mode 100644 index 0000000000..75b8ddd194 --- /dev/null +++ b/website/docs/.vitepress/theme/GlossaryTable.vue @@ -0,0 +1,167 @@ + + + + + diff --git a/website/docs/.vitepress/theme/index.ts b/website/docs/.vitepress/theme/index.ts index d34494d0db..a0dfc816f7 100644 --- a/website/docs/.vitepress/theme/index.ts +++ b/website/docs/.vitepress/theme/index.ts @@ -8,6 +8,8 @@ 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 GlossaryTable from './GlossaryTable.vue'; import LegacyEmailsView from './LegacyEmailsView.vue'; import Page404 from './Page404.vue'; import PageTopTabs from './PageTopTabs.vue'; @@ -31,6 +33,8 @@ export default { app.component('LegacyEmailsView', LegacyEmailsView); app.component('TypesView', TypesView); app.component('DosDonts', DosDonts); + app.component('DosDontsCopy', DosDontsCopy); + app.component('GlossaryTable', GlossaryTable); app.component('Playground', Playground); }, setup() { diff --git a/website/docs/.vitepress/theme/style.css b/website/docs/.vitepress/theme/style.css index ac1a26cc6d..6fcc508883 100644 --- a/website/docs/.vitepress/theme/style.css +++ b/website/docs/.vitepress/theme/style.css @@ -1198,3 +1198,4 @@ h6[class] { .vp-doc li[data-ui-name]+li[data-ui-name] { margin-top: 2px; } + diff --git a/website/docs/content/buttons/buttons.md b/website/docs/content/buttons/buttons.md new file mode 100644 index 0000000000..f94b90a6ed --- /dev/null +++ b/website/docs/content/buttons/buttons.md @@ -0,0 +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/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 new file mode 100644 index 0000000000..383084e838 --- /dev/null +++ b/website/docs/content/content-principles/content-principles.md @@ -0,0 +1,336 @@ +--- +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. + +::: tip +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](/content/glossary/glossary). + +### Race and ethnicity + +Default to the generally accepted descriptors "person of color," "POC," or "BIPOC". See the [Glossary](/content/glossary/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 new file mode 100644 index 0000000000..b49345ffd0 --- /dev/null +++ b/website/docs/content/errors/errors.md @@ -0,0 +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 new file mode 100644 index 0000000000..3c0ffd6bf4 --- /dev/null +++ b/website/docs/content/feedback/feedback.md @@ -0,0 +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/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/glossary/glossary.md b/website/docs/content/glossary/glossary.md new file mode 100644 index 0000000000..990aecd92f --- /dev/null +++ b/website/docs/content/glossary/glossary.md @@ -0,0 +1,7 @@ +--- +title: Glossary +--- + +Preferred terms and what to avoid. Covers inclusive language, American English spelling, and plain language choices. + + diff --git a/website/docs/content/grammar/grammar.md b/website/docs/content/grammar/grammar.md new file mode 100644 index 0000000000..84a342d1b2 --- /dev/null +++ b/website/docs/content/grammar/grammar.md @@ -0,0 +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 new file mode 100644 index 0000000000..8c11c44751 --- /dev/null +++ b/website/docs/content/lists/lists.md @@ -0,0 +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 new file mode 100644 index 0000000000..1a66935aad --- /dev/null +++ b/website/docs/content/modals/modals.md @@ -0,0 +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/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 new file mode 100644 index 0000000000..d4056d56a4 --- /dev/null +++ b/website/docs/content/onboarding/onboarding.md @@ -0,0 +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 new file mode 100644 index 0000000000..2595b22e00 --- /dev/null +++ b/website/docs/content/placeholders/placeholders.md @@ -0,0 +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 new file mode 100644 index 0000000000..4a5678ec16 --- /dev/null +++ b/website/docs/content/pricing-and-sales/pricing-and-sales.md @@ -0,0 +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/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’tDoDon’tDo