Writing Guidelines
These guidelines govern all user-facing text in the Mukoko ecosystem: UI labels, descriptions, help text, marketing copy, and documentation.
The Mukoko voice is:
- Clear — say what you mean in the fewest words necessary
- Warm — friendly without being informal; professional without being cold
- Empowering — help users accomplish their goals; avoid talking down
- Grounded — rooted in practical value, not hype
Tone shifts based on context while the voice stays consistent:
| Context | Tone | Example |
|---|---|---|
| Success | Celebratory, brief | “Payment sent successfully” |
| Error | Calm, helpful | “We could not process the payment. Check your balance and try again.” |
| Onboarding | Welcoming, guiding | “Welcome to mukoko. Let us set up your account.” |
| Documentation | Direct, instructive | “Install the component with the shadcn CLI.” |
| Marketing | Confident, inspiring | “Built for Africa’s digital future.” |
Language conventions
Section titled “Language conventions”Sentence case
Section titled “Sentence case”Use sentence case for all UI text — headings, buttons, labels, tabs:
✓ "Getting started"✗ "Getting Started"
✓ "Add new item"✗ "Add New Item"Exceptions: proper nouns (Africa, Zimbabwe) and brand names (mukoko, Nyuchi).
Active voice
Section titled “Active voice”Use active voice. It is more direct and easier to translate:
✓ "You can install components with the shadcn CLI."✗ "Components can be installed with the shadcn CLI."
✓ "The system saved your changes."✗ "Your changes have been saved by the system."Short sentences
Section titled “Short sentences”Keep sentences under 25 words. Break complex ideas into multiple sentences:
✓ "Components are installed locally. You own the code and can modify it freely."✗ "Components are installed locally into your project where you own the code and can modify it freely to suit your needs."Numbers
Section titled “Numbers”- Use numerals for quantities: “3 components”, “45px touch hit areas”
- Spell out numbers at the start of sentences: “Five minerals form the palette”
- Use numerals for technical values: “0.75rem”, “768px”
Dates and times
Section titled “Dates and times”- Use the user’s locale format when possible
- Fallback to day-month-year: “2 April 2026”
- Use relative time for recent events: “3 hours ago”, “yesterday”
Pan-African audience
Section titled “Pan-African audience”Shona and Ndebele are primary languages in the Mukoko ecosystem, alongside English. Content should be written with translation into these languages in mind from the start. Lingo, a dedicated mukoko mini-app for African language learning, exists as a product — a reminder that language in this ecosystem is not an afterthought but a first-class concern.
Avoid idioms
Section titled “Avoid idioms”Idioms do not translate well and may confuse non-native English speakers:
✓ "Get started quickly"✗ "Hit the ground running"
✓ "This is easy to use"✗ "This is a piece of cake"Avoid cultural assumptions
Section titled “Avoid cultural assumptions”- Do not assume Western holidays, seasons, or cultural references
- Reference shared concepts: seasons differ across Africa (rainy/dry vs four seasons)
- Use universal metaphors when possible
Technical terms
Section titled “Technical terms”- Define technical terms on first use
- Use consistent terminology — pick one term and use it everywhere
- Avoid unnecessary jargon: “set up” not “bootstrap”, “install” not “scaffold”
UI text patterns
Section titled “UI text patterns”Buttons
Section titled “Buttons”Use action verbs that describe what happens:
✓ "Save changes" ✗ "Submit"✓ "Delete account" ✗ "Remove"✓ "Send message" ✗ "OK"Labels
Section titled “Labels”Be specific and concise:
✓ "Email address" ✗ "Email"✓ "Full name" ✗ "Name"✓ "Phone number" ✗ "Phone"Empty states
Section titled “Empty states”Tell users what they can do, not just what is missing:
✓ "No messages yet. Start a conversation to see messages here."✗ "No data found."Confirmation dialogs
Section titled “Confirmation dialogs”State what will happen and whether it can be undone:
Title: "Delete this item?"Body: "This will permanently delete the item and all associated data. This action cannot be undone."Actions: "Delete item" / "Cancel"