8000 GitHub - zakariaf/mindforge: Offline brain-training games for iOS — a Flutter engine that ships many small games from one codebase. Four locales, two right-to-left. No accounts, no ads, no tracking. · GitHub
[go: up one dir, main page]

Skip to content
zakariafPublic

About

Offline brain-training games for iOS — a Flutter engine that ships many small games from one codebase. Four locales, two right-to-left. No accounts, no ads, no tracking.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

MindForge

Train your brain. No wifi needed.
An offline brain-training app for iOS and Android — and an engine for building many small games from one codebase.

License Flutter Platform Locales Status

Five MindForge screens captured from the app: Stroop Rush, Schulte Grid, the home hub listing all four games, Digit Bridge and False Light


Status: 1.0.0 is on the App Store. Twelve epics are merged: the theme, the four locales, the component library, the engine and four games are implemented and tested. The first build was rejected under App Store Guideline 4.3(a); docs/review/app-review-4-3-a.md records what that means and what changed before approval. The image above is captured from the app. The screenshots below are the reference targets under design/sunburst-pop/screens/ that every screen was built and signed off against — they render the design source, not the simulator, so a shipped screen is compared to one rather than replaced by it. Progress is tracked in epics/README.md.

What it is

MindForge is a small collection of brain-training games — reaction, attention and working memory — that runs entirely on your phone.

  • Fully offline. No network code at all. Nothing is uploaded, because there is nowhere to upload to.
  • No accounts. No sign-up, no login, no identity. Your scores live in a database on your device.
  • No ads, no analytics, no tracking. Zero telemetry packages.

It is also an engine. Everything except the game board itself — home, game detail, difficulty select, countdown, the play scaffold, pause, results, stats, settings — is written once and shared. Adding a game means supplying its rules, one board widget and one accent colour; it inherits every screen for free.

The four games:

Game The task
Stroop Rush The word "BLUE" is printed in red. Tap the colour, not the word.
Schulte Grid Find 1 to 25 in order, as fast as you can.
Digit Bridge The same number in two writing systems. Find the one that matches.
False Light One light falls on the whole board. Sweep the tiles it does not reach.

The last two are the app's own. They exist because the first two are public-domain psychology instruments that the App Store already carries in quantity — and each is built on something this app had to solve anyway: Digit Bridge on the numeral pipeline that four locales across two scripts required, False Light on the single light source the whole shape language is built from. docs/review/app-review-4-3-a.md records that in full.

Screens

The design direction is Sunburst Pop — arcade-cabinet joy. Every raised surface is a fill, a 3px solid ink border and one hard offset shadow at zero blur, and it presses down when you touch it.

Home screen: greeting, streak, Daily Mix and the game list Game detail: description, best score and difficulty select Countdown: a large 3 over the game's accent colour Stroop Rush: the word BLUE printed in red above four patterned answer keys

Schulte Grid: a five by five grid of scrambled numbers Digit Bridge: the number 472 in Latin digits above six chips carrying Eastern Arabic numerals False Light: a grid of raised tiles with several pressed flat into the board Results: score, new personal best badge, accuracy and reaction time

Stats: personal bests and a bar chart of recent runs Settings: sound, haptics, reduce motion, colour-blind palette and language

Home · Game detail · Countdown · Stroop Rush
Schulte Grid · Digit Bridge · False Light · Results
Stats · Settings

Browse the full design system at design/sunburst-pop/system.html, all ten screens at design/sunburst-pop/app.html, or the two rejected alternatives from design/index.html.

Accessible by construction

The Stroop answer keys carry a pattern as well as a colour — solid, diagonal stripes, dots, concentric rings — and the stimulus word repeats its own pattern in ink. In a game whose entire mechanic is naming colours, colour-blind support is a correctness requirement, not a preference, so the game is playable without any colour discrimination at all. A Settings toggle additionally swaps the answer set to a colour-blind-safe palette, and that swap changes which colours the round is generated from, not merely how they are painted.

Every text and surface pair in the palette is verified against its WCAG floor by a script that recomputes the contrast ratios from the source values.

Languages

MindForge ships in four locales, two of them right-to-left:

Language Code Direction Numerals
English en LTR 1 2 3
German de LTR 1 2 3
Persian · فارسی fa RTL ۱ ۲ ۳
Kurdish Sorani · کوردیی ناوەندی ckb RTL ۱ ۲ ۳

This is not a translation layer bolted on at the end. Right-to-left reaches every component's geometry, and Eastern Arabic numerals reach the Schulte tiles — which are the numbers 1 to 25.

How this repository is built

Two things here are unusual and worth knowing about before you contribute.

1. The conventions are executable. .claude/skills/ holds 45 skills — 40 general Flutter and Dart engineering conventions, plus 5 that encode the Sunburst Pop design system specifically. They are not style guides. Each carries worked examples and a gate script that fails the build on a violation: a raw hex outside the theme directory, a blurred shadow, a game that tries to navigate, a haptic fired outside the feedback service, a contrast ratio below its floor.

2. The work is planned as epics before it is written. epics/ holds twelve epic files, in dependency order. Each task states its tests before its implementation, the files it touches, the skills to load, and the reference screenshot it is compared against.

.claude/skills/     45 skills: engineering conventions + the design system, with gate scripts
CLAUDE.md           the house rules — read this first
design/             the design exploration; sunburst-pop/ is the chosen direction
  sunburst-pop/
    system.html     authoritative for token values: hexes, radii, shadows, durations, type
    app.html        authoritative for layout and spacing across the ten screens
    screens/        the reference screenshots every implementation is compared against
epics/              the build plan, E01 to E12

Building it

Requires Flutter 3.44.6, Xcode 26.6 and CocoaPods. iOS is the only target that ships today.

flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n
flutter test
flutter run -d C13DDC02-375D-4E1B-8F81-44EB407D09A4   # the canonical simulator

That UDID is an iPhone 14 simulator named MindForge iPhone 14. It is the canonical device because it is exactly 390×844 logical points, matching the reference screenshots. No iPhone 16-class simulator does — the 16 is 393×852 and the 16 Pro is 402×874 — so comparing a build against the references on anything else is not an honest comparison.

MindForge targets iOS and Android. iOS is being built first, so the current epics and the canonical device above are iOS; Android follows once the app runs end to end. Nothing in the architecture is iOS-specific — there is no platform channel and no native UI.

Concretely, the repository holds one platform directory, ios/, and that is a decision rather than an omission:

  • iOS ships. It is the only target generated, built and tested today.
  • Android is deferred, not unsupported. Re-adding it is flutter create --platforms=android . plus one PR to restore the build job. Generating an android/ directory nobody builds, tests or opens costs a Gradle upgrade treadmill for zero shipped value, and test/policy/repo_layout_test.dart asserts its absence with that reason attached.
  • macOS is dropped. It earned its place in an earlier plan only as somewhere to eyeball the app; the canonical simulator does that job better and more honestly, because it is exactly 390×844 while a macOS window is whatever the developer dragged it to.
  • web/, linux/ and windows/ were never in scope.

The bundle identifier is io.applander.mindforge, registered in the Apple Developer account. It was renamed from com.mindforge.mindforge on 2026-08-21 — possible only because nothing had been uploaded yet. A bundle identifier is permanent from the first upload onward, so this one is now fixed.

Contributing

Want to add a game? That is the whole point of the engine, and there is a defined path for it: write an epic, implement it, open a PR. Read CONTRIBUTING.md — it covers the epic format, the TDD requirement, the screenshot comparison and what a reviewable PR looks like.

All pull requests are reviewed and merged by the maintainer.

License

Apache License 2.0. See NOTICE for attribution and third-party asset licensing.

About

Offline brain-training games for iOS — a Flutter engine that ships many small games from one codebase. Four locales, two right-to-left. No accounts, no ads, no tracking.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0