Inspiration
Middle-school maths is often presented as a worksheet of symbols before students have had a chance to build an intuition for what those symbols mean. We wanted to make the first step more tangible: fraction size should be visible, negative numbers should have direction, and an equation should feel like a relationship that must stay balanced.
That idea became MathQuest: a focused learning space for the topics that frequently become confidence barriers for learners aged 11-14. Rather than building a collection of decorative quizzes, we designed each topic around a model students can manipulate, then connected that model to targeted practice and a short fluency challenge.
What it does
MathQuest teaches fractions, integers, and one-variable equations through three connected modes in every topic:
- Explore turns an abstract idea into an interactive model. Learners shade and compare fraction bars, move along a number line while seeing positive and negative chips cancel, and solve equations by applying operations to both sides of a balance scale.
- Practice serves generated questions at an appropriate difficulty level. A three-step hint ladder moves from a nudge to a strategy to a worked step, while common wrong answers trigger feedback that addresses the likely misconception.
- Challenge is a 60-second sprint that rewards accuracy and streaks, raising the difficulty as fluency grows.
The dashboard and progress view make improvement visible through mastery rings, accuracy, best scores, and current level. Progress is saved locally on the device, so learners can return to where they left off without an account.
For correctness, fraction answers are represented as exact rational values instead of floating-point numbers. That means identities such as $$\frac{1}{3} + \frac{1}{6} = \frac{1}{2}$$ remain exact when a learner enters an answer.
How we built it
We built MathQuest as a client-side React and TypeScript app with Vite, Tailwind CSS, and the Astra UI kit. The interface uses the design system's navigation, controls, tabs, badges, modals, and typography tokens, with small purpose-built interactive elements for things like fraction-bar segments and equation chips.
The learning logic is separated from the UI:
- A rational-arithmetic module reduces fractions, parses whole numbers, mixed numbers, fractions, and decimals, and compares answers exactly.
- Seeded generators create reproducible fraction, integer, and equation problems across Warm-up, Core, and Stretch tiers. Each problem includes its exact answer, hints, and misconception-aware distractors.
- A mastery module adapts difficulty: three correct answers in a row promote a learner, while two consecutive misses ease the level back. It stores the learner profile in
localStorageunder a versioned key.
The three exploration experiences were built as dedicated React components: Fraction Quest, Signed Shift, and Balance Break. Motion and live feedback help make changes legible without replacing the mathematical explanation.
Challenges we ran into
The biggest challenge was making the activities feel game-like without allowing the game layer to weaken the maths. We kept the challenge mode separate from instruction, and made every question trace back to an exact, solvable representation.
Fractions required particular care. A visually plausible result is not enough when denominators differ, so the app uses reduced rational values throughout and detects common errors such as adding denominators or finding a common denominator without rewriting numerators. Equations raised a different interaction challenge: every allowed operation has to preserve balance, while an unhelpful division needs a clear explanation rather than a silent failure.
We also had to balance adaptive difficulty with encouragement. The rules are deliberately simple and visible in their effects: progress after sustained success, step back after repeated difficulty, and make hints helpful without treating a hinted solution exactly like an independent one.
Accomplishments that we're proud of
We are proud that the three topics each have a distinct conceptual model instead of sharing the same question-card experience. The fraction bars make equivalence visible, the integer number line and chip model show direction and cancellation, and the balance scale makes the "do the same thing to both sides" rule physical.
We are also proud of the accuracy safeguards behind the interface: deterministic problem generation, exact answer checking, targeted misconception messages, and progress that survives a page reload. The result is a compact app that supports both independent practice and a teacher's quick view of where a learner may need reteaching.
What we learned
We learned that interactivity works best when it exposes a mathematical invariant. Equal-length fraction bars reveal equivalence; opposite integer chips reveal zero pairs; a level scale reveals equality. Those relationships are more memorable than an animation alone.
On the technical side, we learned the value of keeping pedagogical rules in small, testable modules rather than embedding them in components. Separating generation, rational arithmetic, mastery, and presentation made it easier to keep the experience consistent across topics and to explain why an answer is right or wrong.
What's next for MathQuest
Next, we want to expand the teacher workflow with optional cloud-backed class accounts, assignment links, and aggregated misconception insights while keeping the current local-first experience fast and simple. We would also add more accessible interaction alternatives for the manipulatives, richer audio support, and additional middle-school topics such as ratios, geometry, and proportional reasoning.
Most importantly, we would validate the adaptive rules with real learners and teachers. Their feedback would help us tune problem pacing, hint wording, challenge length, and the balance between productive struggle and momentum.
Built With
- astra-ui
- educational
- javascript
- localstorage
- react
- responsive-design
- tailwind-css
- technology
- typescript
- vercel
- vite
