Checkpoint 1 · Grammar cards v2 — the design

Grammar cards v2 — the design

You studied the 9 pilot grammar cards and said they didn't teach anything. This is the redesign — built around one simple idea: you can't memorize a rule statement into being able to use the rule. You only get there by practicing it, one sentence at a time.

ADR-084 · proposed Reviewed: ENR + UI (accept-with-comments, folded in) Personas: RETIREE + KID (advisory) Design only — no code yet
Checkpoints Latest →
The problem

Why the first try didn't teach you anything

Your exact words: "the grammar data we had there didn't actually help us learn the subject, we need something else."

The 9 pilot cards showed you a rule, like "ber- + noun = have," as the card's title — then some example sentences underneath. The problem: the card's front already contained the answer. There was nothing to figure out, nothing to recall, nothing to get wrong. Grading a card like that measures nothing, because you can't fail it.

Here's the deeper reason that design doesn't work, backed by how language actually gets learned: knowing a grammar rule (as a sentence you could recite) and being able to use that rule in a real sentence are two completely different skills. You get the second one only by doing it over and over — applying the rule to new words, in new sentences — not by re-reading the rule itself on a repeating schedule. Every serious language app that teaches grammar (Bunpro being the closest match to what we're building) has landed on the same split: a rich "study page" you can read anytime, completely separate from short, one-sentence-at-a-time practice drills that actually get graded.

So this redesign draws that same line: one un-graded rule page (read it, refer back to it) feeding a handful of small, graded sentence drills — each one asking you to produce the correct form of a word in one specific sentence.

See the difference

Two real cards, rebuilt

Same underlying content from your pilot (the Indonesian "ber-" prefix) — shown the old way, then the new way.

Worked example A — "kerja" (work) → "bekerja" (to work)

Old — the pilot card
Card front
ber- + noun = have
(This IS the rule title. There's nothing for you to answer — the "question" already tells you the rule.)
New — the redesign
Card front — your job: fill the blank
Dia kerja di bank.
"She works at a bank."
grammar
bekerja
Sentence with the answer highlighted
Dia bekerja di bank.
The rule, in one line
ber- verbs — adding "ber-" to a base word turns it into "to do that activity."
How it's built
ber- + BASE → verb
be- before rbel- (belajar)
More examples like this
kerja bekerja (to work)
renang berenang (to swim)
ajar belajar (to study)
Watch out
✗ Wrong: berkerja✓ Right: bekerja
Related rules
ber- + noun = haveber- reduplicated

Worked example B — "nama" (name) → "bernama" (to be named)

New — same pattern, "ber- = have"
Card front — your job: fill the blank
Anak itu nama Ali.
"That child is named Ali."
grammar
bernama
Rule
ber- + noun = "to have that thing" — here, "to have a name."

The three-step hint ladder (using the "bekerja" card)

Stuck on a card? Tapping "hint" walks up this ladder — each tap gives one more clue, never the full answer.

1
Pattern: "This uses the ber- pattern — a prefix that turns a word into an activity."
2
Onset: "It starts with be-."
3
Assembly: "be- + kerja → ?"
The shape

What a grammar card is now

One thing to read. A few small things to practice.

Each grammar rule (like "ber- verbs") becomes one rule page — the write-up you just saw in the reveal above: the rule, how it's formed, examples, the common mistake, related rules. You never get graded on the rule page itself; it's a reference, always available.

Under that rule sit 3 to 5 small sentence cards — the fill-in-the-blank cards, like "Dia ⟦kerja⟧ di bank." Each one is graded completely on its own schedule (Again / Hard / Good / Easy), same as your vocabulary cards today. "Good" means you produced the right form of the word for that specific sentence — not that you can recite the rule.

One rule → several graded practice sentences
Rule page
"ber- verbs" — read anytime, never graded
Card 1
kerja → bekerja
Card 2
renang → berenang
Card 3
ajar → belajar
Each card is its own graded, spaced-repetition schedule — just like your word cards today.
Decisions already made

What you've already told me (so I make sure I heard right)

1
The pilot's card format doesn't work and needs a full rebuild.
Not a tweak — the front, the reveal, the summary row, and the hint all need to change shape for grammar content.
Decided by Frank
2
We need specific, concrete examples — and the underlying data setup needs to change to support that.
Examples aren't a nice-to-have; they're the actual practice material. The database needs new fields to hold them properly (details in Section 12).
Decided by Frank
3
The review-app's settings screen needs its own version for grammar/rules cards.
Section 7 below is the short settings list this unlocks — the first real use of a "per-content-type settings" feature that's been sitting ready since early July.
Decided by Frank
4
Example sentences should draw preferentially from words you already know.
You said "we have good grammar lessons on the words themselves — maybe there's something there." Read as: link new grammar examples back to your existing vocabulary deck wherever possible, rather than introducing unfamiliar words just to illustrate a rule.
Inferred from what you said
5
Clicking to reveal the answer (rather than typing it) is an acceptable starting point.
Not stated outright — inferred because typing free-form Indonesian at A1-A2 risks penalizing correct answers over typos, which would make grading unreliable before the basics are proven out. Flagged as Decision 4 below so you can override it.
Inferred from what you said
Your call

Four decisions — one click each

"Recommended" means: my own best judgment on the merits, worked out independently — not a guess at which one you'll pick.
D1. How many levels should a grammar rule have?

Option A (recommended) — two levels: the rule page, and 3-5 sentence cards under it. Simple, matches how the app already handles cards, and nothing new to build beyond the rule page itself.

Option C — three levels: add a "family" level above the rule — e.g. group all 11 "ber-" rules under one "ber- family" page, the way word families already work. Gives you a bigger-picture curriculum view, but it's an untested shape and costs extra build time for a benefit we can get another way (a simple "related rules" list, already in the design).

Heads up either way This choice touches one sentence in an earlier design doc (ADR-083) and one sentence in the project glossary — both get a small, one-line update to match whichever you pick.
D2. Should each rule's short identifier (e.g. "ber-noun-have") get its own permanent database column, or live in the flexible catch-all area we already use?

Pocket only (recommended): store it in the same flexible per-card storage area every other archetype already uses. Zero new database structure, ships faster, easy to change later.

Real column: gives the database a hard guarantee the identifier always matches something in the master rule list (a foreign key). Slightly safer against typos in the generation pipeline, but it's the one piece of actual database surgery in this whole plan.

D3. Should grammar-rule practice be something a learner turns on, or on by default for everyone?

Per-profile opt-in (recommended): matches how the alphabet/script track already works. When we checked this design against two different learner personas (a retiree and a kid), both were an awkward fit for grammar-rule drilling — not a hard "no," just against the grain of how they naturally study. Opt-in respects that.

Default-on: simpler onboarding, one less setting to explain — but risks putting a dense, adult-facing study format in front of learners it doesn't suit.

D4. Should the sentence cards ask you to type the answer, or just show it and you say whether you got it right?

Reveal-only now, typed later (recommended): you read the sentence, think of the answer, tap to reveal, then grade yourself honestly. Simple to build, no risk of correct answers being marked wrong over spelling/typo issues. Typing can be added as an option later.

Typed from day one: stronger practice (you have to actually produce the word, not just recognize it) but needs careful handling of near-misses, capitalization, and Indonesian's optional spelling variants before it's fair to grade automatically.

The end of a session

What the summary screen looks like with grammar cards mixed in

The overall counts (Again/Hard/Good/Easy, recalled X of Y) don't change — grading works exactly the same underneath. What changes is how each card is listed.
Session summary
14 cards reviewed
Good ×9Easy ×3Hard ×2
WORDS (11)
pilih memilih · Good
terima menerima · Easy
… 9 more
GRAMMAR (3)
bekerja grammarber- verbs · Good
bernama grammarber- + noun = have · Easy
berenang grammarber- verbs · Hard
Reference + help

"Learn" and "Hint" for a grammar card

L
Learn
Opens the rule page — the same write-up shown in the reveal above (rule, formation, examples, caution, related rules). Available any time, at any point in your progress with that rule — not gated behind reaching a certain skill level, the way some word-card features are.
H
Hint
The three-step ladder shown above (pattern → onset → assembly). No mnemonic pictures for grammar rules — those are a word-card feature that doesn't map cleanly onto an abstract pattern like "ber-".
Settings

The settings screen for grammar/rules cards

First real use of the "each card type gets its own settings" feature that's been ready to plug into since early July.
Kept, grammar-specific:
Dropped — doesn't apply to rules:
At scale

How this gets generated for all 126 topics, not just these 2

Hand-authoring is the topic list only. Everything below that is machine-generated and checked.
1
Grammar books already loaded (Sneddon), broken into addressable sections
2 · hand-authored
The rule inventory — the topic skeleton (Section 9), written once by a human
3 · generated
One generation job per rule, on the existing background job queue (a new job type)
4 · generated
Automatic checks — the answer must actually appear in the sentence, at least 2 examples, etc.
5
Cards written to the database, ready for review/release
Note: example sentences are mined preferentially from words already in your deck — the same "maybe there's something there" link from the decisions ledger, made structural.
The curriculum

The topic map — 126 topics, 19 families, 4 books

One deep-dive branch (verbal prefixes/suffixes) was worked all the way down to 45 card-ready rules, to prove the design holds at real depth — 11 of those are just the "ber-" prefix.
All 19 grammar families (126 topics total)
  • Sound & spelling system (this becomes the Script track, Section 11) 5 topics
  • Pronouns & terms of address 9 topics
  • Basic sentence word order 10 topics
  • Negation (saying "not") 8 topics
  • Questions 8 topics
  • Numbers, time & dates 7 topics
  • Classifiers & quantifiers 4 topics
  • Prepositions 4 topics
  • Noun phrases & possession 8 topics
  • Verbal prefixes/suffixes — worked to card-ready depth 1 overview + 45 rules
  • Reduplication (doubling words) 6 topics
  • Passive & object-focus voice 7 topics
  • Imperatives & requests 6 topics
  • Time/aspect markers & modals 10 topics
  • Comparison 5 topics
  • Relative clauses & "yang" 6 topics
  • Particles & discourse markers 7 topics
  • Complex sentences 10 topics
  • Formal vs. casual register 5 topics
The "ber-" branch, worked to card-ready depth (11 rules)
  • Sound changes (be- before r, bel- in belajar) A2
  • ber- + noun = "to have X" (bernama, beranak) A2
  • ber- + noun = "to wear/use/ride X" (bersepeda) A2
  • ber- + noun = "to produce X" (bertelur, berbuah) B1
  • ber- + verb base = "do the activity" (bekerja, berenang) A2
  • ber- for mutual relationship (berteman, berkenalan) B1
  • ber- + number = "in a group of N" (berdua) A2
  • ber-...-an = reciprocal action (bersalaman) B1
  • ber-...-an = many actors/random motion (berjatuhan) B2
  • ber-...-kan = "have X as" (berdasarkan) B2
  • ber- + doubled base (berjalan-jalan) A2
Known gaps, flagged for later:
Reach

Does this work for languages other than Indonesian?

Yes. We paper-checked this whole design against Japanese (a very different grammar system — particles and verb conjugation instead of prefixes) before committing to it. It holds with zero database surgery: the same per-language override mechanism the app already uses for other content covers everything Japanese needs — free-text formation patterns instead of "ber- + base," and an optional field for how a word is read aloud (for kana/kanji). The Indonesian topic map you saw above is content, not part of the underlying design — a different language just gets its own topic map plugged into the same machinery.

What's next

The Script (alphabet) track reuses this exact framework

Right now the Script track has 31 units built (the 26 letters + 5 letter-pairs, one of which — "NK" — looks questionable and needs a second look), but it's missing some sounds (the letter E actually makes two different sounds), the diphthongs (ai/au/oi), and stress rules — and the on-screen renderer isn't finished either.

The same four-question design framework used here re-applies directly. The main differences: what you're practicing is recognizing/hearing a letter, not filling in a blank in a sentence; and since audio is central to letters, the "autoplay audio" default flips back to on (the opposite of grammar cards).

This starts once your 4 decisions above are answered.

Under the hood

What changes in the database