HoneyGuide Design System

00 - Principles

Six rules everything else is built to serve

This system is already visually complete. From here, new work should formalize these ideas - tokens, states, specs - rather than add more colour, more decoration, or more variants. When a new pattern doesn't fit one of these six, that's the system telling you something.

01 · Guide, don't gatekeep

Learning stays open and supportive - no walls where a nudge would do.

02 · Progress feels tangible

XP, path nodes and badges make growth visible, not just counted somewhere.

03 · Identity feels natural

South African culture lives in Musa's details - it doesn't get painted across the UI.

04 · Softness over punishment

A wrong answer is feedback, not a failure state.

05 · Character over decoration

Musa communicates on purpose. He's never just sitting in a corner.

06 · Delight never blocks

Motion, sound and rewards add warmth - nothing ever waits on them.

01 - Brand

Never a teacher. Always a guide.

HoneyGuide teaches South African history, geography, science, languages and civics - the way a good guide does: pointing things out, not testing you on them.

"Musa is your learning companion who guides you through South Africa's history, geography, science, languages and civics."

Never a teacher. Always a guide. ❤

Voice - four pillars

Guide, not teacher

We point things out and let the learner arrive at it. No red pen, no grading tone.

Say"You've got this - try again."

Not this"Incorrect."

Warm, not childish

Plain, encouraging language for a general audience - not baby talk, not exclamation-mark stacking.

Say"Nice - that's the second time this week."

Not this"WOW!! Super duper job!!! 🎉🎉🎉"

Proudly South African, not kitsch

Real references, used in context - not flag emoji decoration or stock "rainbow nation" language.

Say"This is the mountain Capetonians call Table Mountain."

Not this"🇿🇦 Welcome to the Rainbow Nation! 🌈"

Grounded, not trivia-hollow

Every fact earns a "why this matters" - the lesson format is built around that pairing, not a quiz gate.

Saya key fact, then why it still matters today.

Not thisa date and a name with no context.

Values

Learning over testing

No placement assessment gate. Lessons open with a key fact and close with why it matters - not a quiz you have to pass to proceed.

A guide, not a gatekeeper

One full track - History of South Africa - is free to explore before anyone creates an account.

Built on real content

Grounded in a recovered archive of 8 tracks, ~169 lessons and 845 quiz questions - not placeholder copy.

Pride, used sparingly

The flag's colours live in Musa's scarf. They're a detail, not the UI's load-bearing palette.

Naming

HoneyGuide

Named for the greater honeyguide bird - known across Southern Africa for leading people to wild beehives. It shows the way; it doesn't do the work for you. That's the whole product thesis in one animal.

Musa

The mascot's name and its story haven't been formally written up yet. Placeholder - worth a short paragraph here once that's settled (meaning, pronunciation, why this name for this bird).

02 - Colors

Colors

The full token set already used in production. Everything else in this document is built from these values - nothing here is aspirational.

Primary - Jade Green

Jade Light

#3FC79A

Jade Green

#0FA676

Primary brand color

Jade Dark

#0C8560

Deep Green

#21543D

Headings, ink

Secondary - Golden Yellow

Gold Light

#FFD97D

Golden Yellow

#FFC24D

Rewards, streaks, CTAs

Gold Dark

#E0A020

Neutral - Warm Brown

Brown Light

#AD8058

Warm Brown

#8B5E34

Musa's wings, satchel

Brown Dark

#6E4826

Flag accents

Use sparingly - Musa's scarf and small accent moments only. Never as functional UI color (buttons, states, charts).

Red

#DF1F3D

Blue

#1E3A8A

Black

#111111

Supplementary - functional colors

Coral

#FF6B57

Hearts, errors - never used for Musa's own tone

Sky

#3FA9E0

Info, focus rings

Violet

#8B6FD9

Streaks, rare rewards

Backgrounds

Background

#F6EFDD

Background 2

#EFE2C4

Card

#FFFFFF

Card Warm

#FFF9EC

03 - Typography

Typography

Fredoka carries the brand's personality - headings, buttons, anything that should feel spoken by Musa. Manrope handles everything you actually read.

Fredoka

Display - headings, buttons, stat numbers

Manrope

Body - paragraphs, labels, lesson content

Type scale

Display XLFredoka 700 · 34px / 1.1

Display LargeFredoka 600 · 26px / 1.15

Display MediumFredoka 600 · 20px / 1.2

Display SmallFredoka 600 · 15px / 1.3

Body Large - for lesson key facts and anything the learner needs to actually read.Manrope 500 · 16px / 1.6

Body Medium - supporting text, descriptions, card copy.Manrope 400 · 14px / 1.6

Eyebrow LabelFredoka 700 · 11px · uppercase

04 - Icons

Icons

24×24, currentColor, drawn to sit comfortably next to Fredoka. Filled shapes for badges and rewards, 2–2.4px stroke for functional UI icons - don't mix both styles within a single icon.

05 - Musa

The Honeyguide

A young greater honeyguide in an explorer's scarf and satchel. Curious, encouraging, proud of the learner rather than of himself - and never, in any of his fifteen expressions, angry or mocking.

Expressions (15)

Every expression maps to a real product moment. None of them are negative toward the learner - the closest Musa gets to "wrong answer" is Encouraging or Confused, played gently.

Happy - lesson complete · Celebrating - streak milestone · Excited - new track unlocked · Curious - track intro · Thinking - content loading

Encouraging - wrong answer · Confused - used sparingly, paired with a hint · Sleepy - re-engagement nudge · Determined - mid-streak · Proud - hard lesson cleared

Poses

Unlockable accessories

Accessories tie directly into the badge system - they're earned, not cosmetic filler.

Turnaround

Reference for any future 3D, AR, or animated use.

Character animations

Short looping clips of Musa for use anywhere the static artwork needs to feel alive - empty states, loading screens, lesson intros. Each clip is a self-contained loop; none of them carry audio, so they're safe to autoplay muted.

Idle - resting loop, no user action

Reading - lesson content loading / in progress

Walking - transitions between screens or tracks

Waving - greeting, onboarding, sign-off moments

Do's & don'ts

Do Keep the scarf on in every context. Let Musa's expression carry the emotional weight instead of adding !! or CAPS for emphasis. Use Musa to soften hard moments - a wrong answer, an empty state, a lost streak.

Don't Invent a new expression without adding it here first. Use Musa in account, payment, or legal contexts - those need a plainer, non-mascot tone. Recolour the scarf outside the brand palette, or crop/stretch him off-model.

Animation

Musa's idle state is a slow float - the same keyframe used across the app for anything that should feel alive without demanding attention. See the Motion section for the full set and live demos.

Idle float - 3.6s ease-in-out, infinite

06 - Illustration

Illustration

Illustration extends the South African motif through iconography - protea, mountains, coastline - rather than literal flag imagery. The sticker set mirrors Musa's 15 expressions for shareable, in-app moments.

Sticker pack

Scarf: Ndebele-inspired geometric trim, SA colours used as a detail - not a backdrop

07 - Components

Components

Live specimens, not screenshots - this is the actual clay-shadow system running in the app today.

Spacing scale

4px base unit

4

8

12

16

20

24

32

40

48

64

Buttons

Variants - primary / gold / coral / ghost / outline

States - default / hover & focus (try it) / pressed / loading / disabled

Cards & chips

Clay card

History of South Africa

18 lessons · Free track

Chips

BeginnerFeatured

Stats & progress

Stat pills

12 5 340

Progress

Path node - states

Locked / current (active) / default / complete

Badges

Badge tiles

Explorer

Champion

Leaderboard row

2You1,240 XP

3Junior1,180 XP

08 - Motion

Motion

Motion celebrates - it never blocks. Nothing in this list makes the learner wait longer than the interaction actually needs. Tap a button to replay it.

Ambient - idle, no user action

Keyframe	Timing	Used for
float	`3.6s infinite`	Musa's idle state, anywhere he's just present on screen
nodeBounce	`2.2s infinite`	Drawing the eye to the next lesson node on the path
bossPulse	`1.8s infinite`	Milestone / boss-level nodes, idle

Feedback - responds to a user action

countBump	`.4s`	XP / streak counters incrementing
pulseGlow	`.9s`	Drawing attention to a newly-claimable reward

Celebration - a genuine win

confettiFall	`variable`	Track completion, big milestones
trophyBurst	`.7s`	Badge or achievement reveal
starPop	`.4s`	Perfect-lesson star rating

Transition - moving between screens

screenIn	`.32s ease-out`	Full-screen transitions between lessons
sheetUp / sheetPop	`.3s ease-out`	Bottom sheets - answer feedback, track details

Four buckets, deliberately: ambient plays without being asked, feedback replies to what the learner just did, celebration is earned, and transition gets out of the way as fast as it can. If a new animation doesn't obviously belong to one, that's usually a sign it's decorative rather than functional.

09 - Rewards

Rewards

XP, hearts and the leaderboard are MVP, not a later add-on - they're part of how HoneyGuide keeps a guide feeling like a guide instead of a nag.

XP

Earned per lesson. Drives the leaderboard.

Hearts

A soft limit on wrong answers - never a hard stop that feels punishing.

Streak

Consecutive days learning. Losing one is a Sleepy Musa, not a scolding.

Badge evolution ladder

Musa grows with the learner - his scarf and badges evolve at set milestones. This is a real, literal sequence, so it's the one place in this document a numbered ladder actually belongs.

LEVEL 1

Explorer Scarf

LEVEL 10

SA Stripes Unlocked

LEVEL 25

Geometric Trim

LEVEL 50

Protea Badge

LEVEL 100

Master Explorer

10 - Sounds

Sounds

No audio exists yet. This section is principles only, until sound design happens - treat it as a brief for that work, not a spec.

Short, never startling

Sub-second cues at a volume appropriate for a classroom or a bus ride - nothing that makes a phone bark out loud.

No buzzer for wrong answers

A gentle, neutral tone - never an alarm or error-buzzer sound. Matches the "guide, not teacher" voice value.

One triumphant motif

Reused for streak-saves, badge unlocks and track completions, so it becomes recognisable rather than novel each time.

Muted by default is fine

Sound should add delight, not be load-bearing - every cue needs a silent-equivalent (motion, copy) that works alone.

11 - Writing

Writing

UI copy follows the same voice as Musa - because to the learner, it's the same character talking.

Rules

Buttons are imperative and specific

"Start lesson," not "Submit" or "Go." The label says exactly what happens next.

Wrong answers get the right answer back

Encouragement plus the correct answer, restated - never just "Wrong."

Empty states are an invitation

Say what's missing and what to do about it - never a dead end with no next step.

One exclamation mark, max

Never stack enthusiasm across a whole message - it reads as hollow, not warm.

Before / after

"Submission failed. Please try again."

"That didn't save - give it another go."

"No data available."

"Nothing here yet - start your first lesson to see progress."

"Incorrect! Try harder!!"

"Not quite - it's actually Pretoria. You'll get the next one."

12 - Accessibility

Accessibility

Already built into the app's CSS - documented here so it stays true as the product grows.

Contrast - measured, not assumed

Checking this table against the real hex values caught two real failures - white text on the gold and coral buttons was reading at 1.6:1 and 2.8:1. Both are fixed in this version: gold buttons now use dark brown text, coral buttons use near-black, and the primary green button uses its darker tone so white text clears 4.5:1.

Text	On	Ratio	Standard
Ink #21543D	Background #F6EFDD	7.6:1	AA text ✓
Ink-soft #4C6659	Card #FFFFFF	6.3:1	AA text ✓
White	Primary button (green-dk)	4.6:1	AA text ✓
Brown-dk #6E4826	Gold button	5.0:1	AA text ✓
Black #111111	Coral button	6.7:1	AA text ✓
Icon fill #7A4E00	Gold badge	4.5:1	AA non-text (3:1) ✓

Icons and badges are graded against the 3:1 non-text standard, not the 4.5:1 text standard - they're carrying a shape, not a sentence. Anywhere a color sits behind actual words, it's held to 4.5:1.

The voice, world & interface behind Musa the Honeyguide.