Writing Guidelines

These guidelines govern all user-facing text in the Mukoko ecosystem: UI labels, descriptions, help text, marketing copy, and documentation.

Voice

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

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

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

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

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

Use numerals for quantities: “3 components”, “48px touch targets”
Spell out numbers at the start of sentences: “Five minerals form the palette”
Use numerals for technical values: “0.75rem”, “768px”

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

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

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

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

Buttons

Use action verbs that describe what happens:


✓ "Save changes"    ✗ "Submit"
✓ "Delete account"  ✗ "Remove"
✓ "Send message"    ✗ "OK"

Labels

Be specific and concise:


✓ "Email address"   ✗ "Email"
✓ "Full name"       ✗ "Name"
✓ "Phone number"    ✗ "Phone"

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

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"