feat(docs): add UX writing content guidelines

apps/apollo-docs/app/content/_meta.ts

@@ -0,0 +1,7 @@
+export default {
+  'voice-and-tone': 'Voice and tone',
+  'capitalization-and-punctuation': 'Capitalization & punctuation',
+  'inclusive-writing': 'Inclusive writing',
+  'writing-for-translation': 'Writing for translation',
+  terminology: 'Terminology',
+};

apps/apollo-docs/app/content/capitalization-and-punctuation/page.mdx

@@ -0,0 +1,77 @@
+# Capitalization and punctuation
+
+## Capitalization
+
+Use sentence case everywhere — headings, titles, CTAs, navigation items, labels. Capitalize only the first letter of the first word.
+
+### Capitalize
+
+- Proper names
+- Branded standalone products
+- Licensed or branded features
+- First word of a sentence
+
+### Don't capitalize
+
+- Feature names (e.g. automation template, test case, job monitoring)
+- Non-branded subfeatures
+- Product-specific features that aren't proper nouns
+
+---
+
+## Abbreviations and acronyms
+
+Use abbreviations only if they're common and globally understood. Avoid them when possible.
+
+On first use, spell out the term with the abbreviation in parentheses — for example: "software as a service (SaaS)."
+
+**Exceptions — no expansion needed:** FAQ, URL, JSON, MP3.
+
+### Latin abbreviations
+
+In user-facing copy, use plain-language alternatives — these abbreviations are easily confused with each other and add friction for translation and non-native readers.
+
+| Instead of | Use |
+|---|---|
+| e.g. | such as, for example |
+| i.e. | that is |
+
+In placeholder text, don't use "e.g." at all — the value shown already reads as an example, so the label is redundant.
+
+---
+
+## Punctuation
+
+### Commas
+
+- Use the Oxford (serial) comma before a conjunction in a series of three or more items.
+- Include a comma before "then."
+- Use a comma with a full date (month, day, year). No comma for month/year or month/day only.
+
+### Hyphens (-)
+
+Joins words without spaces. Use when a compound modifier precedes a noun (e.g. "sign-in instructions"). Don't use for verbs when the noun is a single word.
+
+### Em dash (—) and en dash (–)
+
+- **Em dash** — use to create an interruption or aside in a sentence.
+- **En dash** – use to express ranges (time, years, amounts).
+
+### Ellipsis (...)
+
+Use only for:
+- Truncated or overflow text
+- Loading actions
+- Omissions in quoted text
+
+**Never truncate:** headings, navigation or button labels, essential descriptors, error messages, unique identifiers, or form labels.
+
+### Periods
+
+**Use periods after:** complete sentences in body text, descriptions, subtitles, modals with full sentences, sentences followed by a link or code, and help text under form fields.
+
+**Don't use periods in:** sentence fragments, headings, titles, labels, buttons, banners with fragments, bulleted lists with fragments, placeholder or hint text, navigation items, tooltips with a single sentence, or radio/checkbox text.
+
+### Exclamation points
+
+Avoid in UI. The only exception is greetings (e.g. "Hi, Satya!"). Never use for negative emotions. One per screen maximum — never multiple (!!!). Avoid interjections like "Oops!" or "Wow!".

apps/apollo-docs/app/content/inclusive-writing/page.mdx

@@ -0,0 +1,45 @@
+import { Callout } from 'nextra/components'
+
+# Inclusive writing
+
+Writing inclusively means using language that respects and includes everyone — regardless of ability, background, identity, or experience.
+
+---
+
+## Core practices
+
+**Be aware** — Consider how language may be perceived by diverse audiences. Avoid assumptions about ability, background, identity, or experience.
+
+**Connect and empathize** — Write as if talking to a real person. Use "you" to address the user directly. Focus on what they can do, not what they can't.
+
+**Don't assume or judge** — Avoid language that implies a default or norm (e.g. "normal user," "advanced user"). Don't make assumptions about gender, relationship status, age, or technical skill.
+
+---
+
+## Gender-neutral language
+
+Use "they/them" when gender is unknown or when referring to a generic user. Avoid "he/she" or gendered job titles when a neutral option exists.
+
+| Instead of | Use |
+|---|---|
+| He/she completed the task | They completed the task |
+| Chairman | Chairperson |
+| Manpower | Workforce |
+
+---
+
+## Ability and skill
+
+Avoid describing tasks as "simple" or "easy" — what's easy for one person may not be for another. Offer support without condescension.
+
+<Callout type="warning">
+  Avoid: "Just click the button to get started" or "Simply configure your settings."
+</Callout>
+
+---
+
+## Keep labels short and universal
+
+- Keep labels short; avoid punctuation after labels.
+- Be clear, concise, and specific.
+- Use language that's globally understood — avoid idioms, slang, and culturally specific references.

apps/apollo-docs/app/content/terminology/page.mdx

@@ -0,0 +1,150 @@
+# Terminology
+
+Consistent terminology reduces confusion and improves translation accuracy. Use these definitions across all product copy.
+
+## Platform terms
+
+| Term | Usage |
+|---|---|
+| **Activity** | A specific action or task performed by a robot within an automation. |
+| **Add** | Use when placing an item into a container you're already working in — a list, node, group, schema, or other parent element. Pairs with Remove. Examples: Add input, Add output, Add condition, Add variable update, Add field. Don't use "Add new." |
+| **Automation** | The use of a robot to perform business process steps with minimal human intervention. |
+| **Build** | Use instead of Create for agents, automations, apps, and connectors. Examples: Build an agent, Build a connector. |
+| **Create** | Use when making a new standalone object with its own identity and lifecycle. Omit "new" — it's redundant. Pairs with Delete. Don't use for agents, automations, apps, or connectors (use **Build**). Examples: Create entity record, Create a model, Create a project. |
+| **Execute** | Do not use in the context of automations or jobs. |
+| **Job** | The Orchestrator object for a scheduled or triggered automation instance. Never use as a verb (use **Run**). Job and Run coexist: Job = the Orchestrator object; Run = a single execution. |
+| **New** | Indicates the state of a record. Don't use as a verb or in place of **Add** or **Create**. |
+| **Run** | Use as a verb for a robot performing automated tasks. Also acceptable as a noun to mean a single execution — such as "Stop the entire run," "View the latest run," or the "Runs" table header. When a standalone string risks noun/verb ambiguity, use a descriptive string key (such as `..._COLUMN_RUNS`) for translators rather than avoiding the noun. |
+| **Select** | Use instead of "Choose" for clickable items. Avoid "Deselect" — use **Clear** instead. |
+| **Settings** | Configurable aspects of the application. Use as link text for pages managing application settings. |
+| **Trigger** | An event or condition that initiates an automation. |
+| **Try again** | Use for retry interactions. Don't use "retry." |
+| **Workflow** | Structured sequence of steps built on the platform to coordinate tasks across humans, robots, and AI agents. |
+
+**Add vs. Create — tie-breaker:** If the action's primary purpose is placing an item into a container, use Add. If the object stands on its own, use Create (or Build for agents, automations, apps, and connectors). The opposite-action test confirms it: if the natural undo is Remove, it's Add; if it's Delete, it's Create.
+
+---
+
+## Component copy guidelines
+
+### Button
+
+Use clear verbs; verb + noun when possible. CTAs: 2–4 words maximum.
+
+Don't use "Click here" or "Go to somewhere." Use specific actions (e.g. "Access in...", "Manage in...").
+
+### Badge
+
+One to two words maximum. Avoid wrapping.
+
+### Checkbox
+
+Keep labels short and descriptive.
+
+### Dropdown
+
+Labels should be clear and purposeful. Use short, unique names for all options. Make sure no two options start with the same word or phrase.
+
+### Link
+
+Make all links unique and descriptive. Don't use "Learn more" or "Click here." Don't use the word "link" in the text. Links to the same destination should use consistent link text.
+
+### List
+
+Begin list items with a capital letter. Maintain consistency for scannability.
+
+### Modal
+
+- **Title** — Direct and descriptive.
+- **Body** — Concise. Include only what the user needs to act.
+- **CTAs** — Primary CTA on the right; secondary CTA to the left.
+
+**Example:**
+- Title: Delete this automation?
+- Body: This will permanently remove the automation and all associated logs. You can't undo this action.
+- Actions: [Cancel] [Delete]
+
+### Drawer
+
+- **Header** — Clearly state the purpose (e.g. "Edit project settings").
+- **Sections** — Use labeled sections and grouping to support skimming.
+- **CTAs** — One primary action, typically "Save" or "Apply." Add "Cancel" or "Discard" where needed.
+
+### Search fields
+
+Do: "Search by name or keyword" / "Search projects or automations"
+
+Don't: "Search..."
+
+Don't rely on placeholder text for critical instruction. Include labels and/or helper text as needed.
+
+### Filter labels
+
+Labels should be nouns, not verbs. Keep labels unique.
+
+**Clearing actions:**
+- Do: "Clear all filters" / "Reset filters"
+- Don't: "Cancel" / "X"
+
+**Empty state for filtered view:** "No results match your filters. Try adjusting or clearing your filters."
+
+### Expandable content (accordions)
+
+Use clear, neutral triggers: "Show advanced settings", "View details", "Expand task history."
+
+Avoid casual language: "Sneak peek", "Unlock more."
+
+### Page headings
+
+Use noun-based labels, not action phrases. Exception: modals may use action verbs.
+
+- Do: "Process overview", "Configuration details", "Output parameters"
+- Don't: "Learn about processes", "Configure the settings", "View output"
+
+### Tabs
+
+- Order tabs by relevance — first tab should be the most logical starting view.
+- Sequence tabs by association.
+- Labels should provide clear, concise explanations of the content within.
+
+### Text input
+
+- Labels appear above the field; never use placeholder text instead of a label.
+- Placeholder text is an additional hint or example; avoid using it when possible.
+- Helper text below the field can show examples, syntax, or character count. Max two sentences.
+
+### Toggle switch
+
+- Always include labels or surrounding context.
+- Be clear about what the switch turns on/off. Don't frame the label as a question.
+- The label should not change when its state changes.
+
+### Tooltip
+
+- Use sparingly for supplementary, nonessential info. Never for critical info, errors, long text, or interactive content.
+- Limit to ~2 lines; icon button tooltips: one or two words.
+- Don't repeat the parent element's copy.
+
+### Empty states
+
+- Clear headline.
+- Helpful, actionable guidance.
+- Appropriate CTA.
+
+### Error messages
+
+**Tone:** Neutral and calm. Avoid blame (e.g. "you forgot…"). Avoid dramatizing ("Oops!" or "Something went terribly wrong!").
+
+**Structure:**
+1. What happened — Briefly describe the issue in user-facing terms.
+2. Why it matters (optional) — Provide context only if it helps resolution.
+3. What to do next — Give a clear recovery action.
+
+Do: "We couldn't save your changes. Check your connection and try again."
+
+Don't: "Oops! Something went wrong."
+
+**When not to show an error:**
+- Avoid errors for known or expected system states (e.g. no search results).
+- Show errors inline where possible (e.g. next to a form field).
+- Don't repeat error messages in multiple places.

apps/apollo-docs/app/content/voice-and-tone/page.mdx

@@ -0,0 +1,67 @@
+# Voice and tone
+
+Apollo's voice is simple, consistent, and human. It helps users accomplish their goals without getting in the way.
+
+## Core principles
+
+| Principle | Description |
+|---|---|
+| **Simple** | Use plain, accessible language. Aim for a grade 6 reading level. |
+| **Consistent** | Apply rules uniformly across all content. |
+| **User-centric** | Focus on helping users accomplish their goals. |
+| **Conversational** | Maintain a friendly, natural tone. |
+| **Accessible** | Use language that's globally understood. |
+
+---
+
+## Tone
+
+Our default tone is natural and conversational — not stiff or overly formal. For task-oriented contexts, be direct and clear, like a collaborator rather than a manual.
+
+- Avoid dense blocks of text; prioritize readability.
+- Avoid jargon unless the user is clearly an expert.
+- "Show, don't tell" — don't explain what you're doing; just do it.
+
+---
+
+## Contractions
+
+Use common contractions to keep the tone natural and approachable.
+
+**Use:** aren't, can't, couldn't, didn't, doesn't, don't, hasn't, haven't, isn't, it's, let's, shouldn't, that's, there's, they're, they've, wasn't, we'll, we're, weren't, what's, where's, won't, you'll, you're, you've
+
+**Avoid:** Regional contractions (ain't, y'all, twas) and overly formal alternatives (do not, cannot).
+
+In error messages, use contractions sparingly to maintain a calm, neutral tone.
+
+---
+
+## Numerals
+
+Use numerals instead of spelling out numbers in UI.
+
+**Do:** "Select up to 3 items" / "Data is stored for 48 hours"
+
+Use numerals for all numbers, even at sentence start. For large numbers, combine numerals and letters (e.g. "7 million").
+
+---
+
+## Emphasis
+
+Use one form of emphasis at a time.
+
+| Type | Use for |
+|---|---|
+| **Bold** | Interactive component names in action descriptions only. Never for location names (e.g. column headers). |
+| *Italics* | Additional information — helper text, clarifications. |
+| Underline | Links only. Never for emphasis. |
+| Quotation marks | Single quotes (') for user-entered UI values; double quotes (") for external statements. Never for emphasis. |
+| Color | Urgency or status only. Always pair with another cue (bold, icon) for accessibility. |
+
+Never use emojis in product UI.
+
+---
+
+## Exclamation points
+
+Avoid in most contexts — they can read as shouting. The only exception is greetings (e.g. "Hi, Satya!"). Never use for negative emotions, and never more than one per screen.