Immersive Redesign and Extension Design

Status: living design doc for the #280 redesign epic; the authoritative product/technical design.

This is the design artifact for the Immersive redesign and extension. It includes the future product model, technical design, sitemap, and Claude Design handoff brief.

Confirmed against current codebase state: grammar_masteries, vocabulary_entries, writing_submissions, peer_grades, user_access_grants, document_revisions, and user_voice_preferences remain unbuilt as designed; GrammarExercise.count is still 0; onboarding is still pre-signup-only; the five-tab primary nav is not yet built. The Decks::ReviewsController#submit_review authorization gap and the deck Study button wiring are fixed. Decks folder organization shipped as flat DeckFolder, superseding the shared generic Folder model this doc originally proposed. Documents foldering does not mirror that flat pattern — DocumentFolder (#286) is self-referential/nested, which is the right shape for Documents specifically (see Core Data Model). review_sessions/card_sources tables and models exist and are actually used (Decks::ReviewsController calls ReviewSession.find_or_create_active and passes it into Card#record_review!), and the StudyTracking controller concern is included in the verbs/documents/grammar_notes/conjugations controllers. See “Current-State Codebase Summary” and “Core Data Model” below for detail. See companion document docs/features/immersive_business_plan.md for monetization, marketing, and growth strategy, which this doc does not cover.

Executive Summary

Future Immersive is a focused language-learning workspace whose core premise is cross-linguistic transfer: a learner who already knows one or more of the six Bridge languages (English, Spanish, French, Italian, Portuguese, Catalan) should be able to acquire another one faster, by explicit comparison against what they already know, not by learning it in isolation the way a generic SRS app would treat any language. That premise is expressed through one durable study loop: encounter language (annotated against the learner’s known Bridge language(s) wherever useful), turn the important pieces into reviewable cards, schedule review with FSRS, and show progress in a way that helps the learner choose the next useful action.

The public product remains a practical verb conjugator rather than a marketing landing page. That matters for market fit: a learner can get value before signing up, and the app can convert from a real utility moment into saved verbs, example sentences, and decks.

The signed-in product has five primary areas:

Decks: Anki-style decks and folders backed by the existing Deck, Card, Review, and FSRS foundation.
Documents: reading, translation, audio, dictation, writing prompts, correction, and vocabulary collection from real learner material.
Profile: the learner command center with progress map, activity, peer/teacher feedback, vocabulary, chat history, permissions, and account settings.
Grammar: grammar by level and area, with notes, exercises, review cards, and mastery states.
Verbs: public-first and signed-in conjugation study, with tables, audio, examples, and deck creation.

Grammar becomes a progress system rather than a static library. Notes are organized by CEFR level and category, exercises become flashcards, and the Profile progress map shows concept ratings, effort, due states, and weak areas across the learner’s work. Verbs remain public-first but become a first-class signed-in workspace for conjugation study and deck creation. Documents become learning sources that feed vocabulary, writing practice, and review. Chat is contextual across reviews, grammar, documents, writing, verbs, and profile rather than a separate island.

The market need to test next is whether this unified loop is compelling enough versus the tools learners already combine today: Anki for memory, conjugators for verbs, grammar sites for rules, translators for reading, writing checkers for feedback, and tutors/teachers for accountability. The design hypothesis is that Immersive wins by connecting those fragments into one restrained, serious, progress-aware workflow and by making the learner’s existing Bridge-language knowledge a visible, structural accelerant rather than an implicit assumption — without becoming a game or a generic course app.

Product Direction

The final direction is a companion to serious language learning outside the app: classroom work, books, tutors, conversation, travel, and self-study. Immersive should help the learner bring that material into one progress-aware workspace, then turn the important pieces into durable review. It should feel warm, useful, progress-oriented, and restrained: more like a serious learning instrument than a game, with enough encouragement to support daily study without forcing a rigid path.

Confirmed visual register (Sean, 2026-07-17): the bridge contrastive components as shipped (/admin/design_system/bridge, PR #367 — equivalence table, grammar callout, sentence decomposition, annotated line-numbered reading) are the reference point for the app’s style: subtle, intellectual, academic — the visual language of a well-set textbook’s scholarly apparatus rather than a dashboard or a game. Concretely, in these components that means: hairline --color-border rules and muted ink instead of filled boxes; typography and spacing doing the structural work (small uppercase language chips, baseline-aligned comparison rows, italic examples, dotted underlines, counter-based line numbers in the margin); the single accent color used sparingly and meaningfully (marking the target language, nothing decorative); information-dense but calm. This register may still evolve, but new and redesigned surfaces should aim for it, and Claude Design briefs should cite it as the direction.

Design and product principles:

No typical signed-out marketing landing page. The public entry remains the verb conjugator.
Use one visual direction. Claude Design should explore within the serious learning companion direction.
Keep the current Rails, Turbo, Stimulus, custom CSS, and semantic token system.
Use rows, grouped sections, compact panels, and progress elements with restraint.
Keep index pages as list rows, not card grids.
Put repeatable tests on the existing FSRS/card foundation.
Use Decks, Documents, Profile, Grammar, and Verbs as authenticated primary tabs on mobile and desktop.
Make Profile the learner command center, while Grammar and Verbs remain first-class study workspaces.
Treat chat as contextual coaching woven into the workflow.
Keep all new UI strings localizable.
Make cross-Bridge-language comparison a visible, structural pattern in Grammar and Documents (see “Product North Star” and “EuRom5-Informed Contrastive Patterns”), not just a marketing narrative layered on top of a language-agnostic product.

Current-State Codebase Summary

Current local data snapshot:

Model	Count
Cards	3,228
Decks	9
Reviews	218
Grammar categories	517
Grammar notes	1,913
Grammar exercises	0
Documents	9
Verb lemmas	13,526
Conjugations	1,341,156
Tenses	94
Study events	0
User abilities	0

Application Shape

The app is already organized around the requested domains. config/routes.rb draws admin, api, info, resources, users, and decks. The public root is resources/verbs#index, which matches the product requirement that the signed-out web version remain a verb conjugator instead of a typical landing page.

Current route groups:

Public verbs: /, /verbs, verb detail, and conjugation detail use Resources::VerbsController and Resources::ConjugationsController.
Grammar: /grammar, grammar categories, grammar notes, and grammar exercise check routes exist under resources.
Documents: /documents, bookmarked documents, document words, and document coach routes exist under resources.
Decks: /decks, nested word/sentence/verb/number/text card creation routes, review routes, public decks, copy, choose, and Anki export exist under decks.
Users/profile: Devise, invitations, /profile, /dashboards, /account_settings, GDPR export, and /user_informations/new exist under users.
Public info/support: /faq, /about, /contact_us, /contacts/new, /privacy, /terms, /cookies, /anki, language-interest, subscription, signed-up, and mobile-app info routes exist under info.
API: document sentence/word translation, resource audio, and /api/v1/study_events exist under api.
Admin: ActiveAdmin resources and Sidekiq admin are already present.

The authenticated root is not currently a distinct post-login profile surface. After sign in, the app falls back to stored location or /. The proposed “account created -> onboarding -> profile progress” flow needs explicit routing and controller work.

Existing Learning Foundation

The card and review foundation is real and should be reused, but it should become more flexible than the current subtype shape. Card currently uses card_type as an STI-style inheritance column with subclasses such as WordCard, SentenceCard, VerbCard, and NumberCard. Cards already store FSRS state: difficulty, stability, due date, elapsed days, lapses, reps, scheduled days, status, and last review time. Card#record_review! delegates scheduling to Reviews::FsrsScheduler, creates a Review, and updates the card state.

The redesign should treat Card as the scheduled memory item, not as the full definition of every possible test. The durable card record should own scheduling, deck membership, language pair, ownership, and review history. The test behavior should move toward a template-driven layer where a card can point to a template_key, template_version, prompt_payload, answer_payload, and source links. Ruby template classes can then handle prompt rendering, answer evaluation, hints, audio targets, accepted answers, and supported modes. Existing STI classes remain compatibility paths, but new grammar, document, dictation, writing, and AI-generated card types should not require a new database subclass every time the product adds a test format.

Review is polymorphic through reviewable, belongs to a user, and stores ease, interval, mode, auto-grading fields, user answer, review type, pronunciation fields, and FSRS before/after snapshots. review_sessions exists and is actually used — Decks::ReviewsController calls ReviewSession.find_or_create_active(user:, deck:, mode:) and passes the result into Card#record_review!, so review history is grouped into sessions rather than only individual graded attempts.

StudyEvent and UserAbility tables already exist and are conceptually useful for activity charts, vocabulary/proficiency rollups, and “next best action” recommendations. Card#record_review! calls StudyEventLogger on every review, and the StudyTracking controller concern is included in the verbs/documents/grammar_notes/conjugations controllers, so both tables are populated in normal use. What’s still missing is the rollup layer: no grammar mastery table, activity-graph cache, or “next best action” recommendation service reads this data yet.

Design implication: the redesign should not create a second SRS engine. Extend Card, Review, StudyEvent, and UserAbility, and add template/source/session layers where the current schema is too narrow.

Decks

Deck is both the current storage model and the product language. It supports user ownership, public decks, copying, Anki export, card counts, daily review/new limits, target/fluent language, bookmarking/tagging, and review entry points. This is a strong base for the requested Anki-style Decks tab.

Current limits:

decks.user_id is required. System-owned/prebuilt decks and assets should use User::IMMERSIVE_USER_ID = 1, not user_id: nil.
folders exists in the schema with user_id, parent_id, language, and title, but there is no Folder model, no deck folder_id, and no folder route/controller surface.
Reviews are not grouped into sessions.
Several legacy app/services/cards/* services still reference pre-Deck naming, CardList, and stale card classes. The active deck card flows appear to use the newer Decks::*CardsController and Decks::Cards::* patterns instead.
Decks::DecksController#create_content references Decks::Content::CreateService, but that class was not found. That path should be audited before building new deck generation on it.

Design implication: keep the existing Deck model and use Decks consistently in product copy. Folder support and prebuilt deck ownership/subscription need a clear migration plan.

Grammar

Grammar content is already a major data asset. The schema has curricula, categories, learning objectives, grammar notes, note translations, and grammar exercises. The local database has 1,913 grammar notes and 517 grammar categories, but no grammar exercises.

GrammarNote and GrammarCategory support published content, CEFR levels, target language, slugs, markdown/note fields, translations, and associations. Current grammar views let a user browse categories and notes, read translations, and run a basic exercise check route when exercises exist.

Current limits:

Grammar exercise checking is exact-answer oriented and not connected to cards, reviews, FSRS, study events, or user ability.
There is no grammar mastery table, grammar progress chart, prerequisite graph, recommendation service, or cached level/category/note rollup.
The current content is note-heavy but exercise-light, so the redesign needs a grammar exercise/card generation pass rather than assuming exercises already cover the curriculum.

Design implication: build grammar progress on the existing note/category content, then generate or attach FSRS-backed cards for note exercises. The progress chart should treat unstudied notes as zero until cards/reviews or explicit mastery evidence exist.

Documents

Documents currently provide a useful but narrow reading flow. Document, DocumentSentence, and DocumentWord exist. Documents belong to a user, have title/content/language/level/job fields, and are processed by a background job that segments sentences and words. The reader can show sentence and word views, translate selected sentences/words through API endpoints, create audio, and open a coach route.

The current implementation is plain-text oriented, which is an advantage for language processing. Resources::Documents::ProcessJob already segments sentences, tokenizes words, evaluates level, and counts words from documents.content. The redesign should preserve that processing clarity even if the authoring experience gains basic formatting.

Current limits:

Documents are flat; there is no document folder/files hierarchy.
Upload/OCR for PDFs, photos, and images is not present in the current document model surface.
The coach service is currently a simulated placeholder with the LLM call commented out.
Dictation, handwritten/photo correction, writing prompts, writing feedback, and CEFR writing grades are not modeled yet.
Basic formatting is not modeled yet; edit mode is a plain textarea.
Document sentence/word API lookup should be audited for ownership/authorization before expanding the feature; the controllers find sentence/word records directly by id.

Design implication: reuse the existing document, sentence, and word segmentation foundation. Add upload/import metadata, foldering, interaction events, dictation, writing feedback, voice preferences, edit history, and a real context-aware coach. If formatted authoring is added, markdown or a constrained markdown-like format should be treated as the authoring layer; the reader must still render through Immersive’s sentence/word-aware document renderer rather than raw markdown HTML.

Verbs

Verbs are the most mature public content area. VerbLemma, Tense, Infinitive, Verbal, and Conjugation provide a large conjugation dataset for the six requested languages. The local database has more than 1.3 million conjugations.

The public verb controllers already support language selection, search, verb details, conjugation grouping by mood/tense, translations, validation jobs, example sentence lookup, and AI sentence generation when examples are missing. The agent stack includes prompt/schema/job patterns for validation and generation.

Current limits:

Verb-to-deck creation exists only indirectly through deck card flows and public deck links.
Audio/example coverage needs auditing in the browser review and implementation pass.
CEFR mapping by tense/mood/verb group is not visible as a first-class model.

Design implication: keep verbs public-first, then add signed-in actions that create decks/cards from verb, tense, mood, or weak conjugation context.

Users, Profile, Onboarding, and Permissions

User already carries target and fluent language fields, profile fields, Devise auth, invitations, admin/impersonation hooks, Ahoy, and PaperTrail expectations. Language constants already include the requested languages: ca, en, es, fr, it, pt. fluent_language is a single string column — see “Product North Star” for why this is now a flagged gap, not just a schema detail: the north star assumes a learner may know more than one Bridge language, which the current single-column model can’t represent.

Current onboarding is pre-signup language capture through /user_informations/new, with the result stored in session and merged into Devise registration params. The requested first-account onboarding needs a post-account flow with language, level, optional subscription, and profile landing.

Current profile/account areas are basic. There is no implemented profile tab shell for Progress, Activity, Evaluate, Vocabulary, Chat History, Teacher Permissions, or Billing grouping. There is no peer grade model, QR/barcode grading flow, teacher access grant model, vocabulary list model, or activity heatmap rollup yet.

Design implication: Profile should become a new authenticated shell area rather than a light extension of the current user show/edit pages. Language onboarding should preserve the existing pre-signup capture where useful but add a first-run profile setup path.

Chat and AI

The app already has substantial AI infrastructure: app/prompts, app/schemas, RubyLLM models/tables, and AWS service patterns.

RubyLLM persistence tables exist for chats/messages/tool calls/models, but the app does not yet expose a user-facing chat surface, and the chat records do not currently show user ownership or contextual source ownership in the schema.

Design implication: “Chat everywhere” should be built as an app-owned wrapper around the existing AI stack. Add user ownership, context source links, privacy rules, and a context builder instead of inventing a detached chat subsystem.

Design System and UI Code

The current CSS foundation matches the requested direction well. _global.css defines CSS layers, semantic OKLCh tokens, dark mode semantic overrides, system fonts, focus rings, buttons, badges, and restrained primitives. list-row.css and shared/_list_grid.html.erb support the list-row index pattern required by the repo guidance.

Current limits:

Some CSS files still use older/raw token names or fallback hex values.
Grammar/document/deck views need browser review for information density, mobile behavior, and navigation fit.
The current design system is good enough to extend; it does not need replacement.

Design implication: Claude Design should work inside the existing design language and produce incremental component additions, especially for tabs, segmented controls, progress charts, review controls, activity heatmaps, and contextual chat.

Testing and Implementation Risk

The test suite is Minitest with fixtures, Mocha, WebMock, and Cuprite system tests. Existing tests cover policies, models, deck reviews, grammar filters, public pages, study event/user ability behavior, jobs, and agent paths. External API calls are stubbed by default; LIVE_MODE=true enables real services.

Risks to resolve before or during implementation:

Use rbenv Ruby for Rails commands; system Ruby is not suitable.
Keep Pundit/ownership checks front and center as document APIs and deck review routes expand.
Avoid building on stale legacy card services until they are removed or reconciled.
Decide whether generic folders should serve decks, documents, or both, or whether domain-specific folders are cleaner.
Add review sessions before exposing detailed review history, streaks, and accuracy summaries.
Add source links from cards/reviews/study events before building unified progress.
Localize all new UI strings.
Keep CSS changes flat, token-based, and consistent with existing layers.

Existing UI and Browser Flow

The current browser surfaces confirm that Immersive already has useful raw material: a public verb utility, compact list-row indexes, FSRS review controls, bilingual grammar notes, and a document reader. The redesign should preserve those strengths while making the signed-in product feel like one coherent learning workspace.

The signed-out root already behaves like the requested public product entry: a verb search/conjugator page, not a generic marketing landing page. The header exposes language pair selection, log in, and sign up. The verb list is compact and useful, and the footer carries public links and newsletter signup.

The login form is simple and focused. After login, the app returns to /, which is still the verb conjugator. There is no first-run redirect into onboarding, profile progress, or an authenticated dashboard.

Design implication: keep the public root as the verb utility, but split the signed-in landing behavior so returning users can land in Profile or their last primary tab while public visitors still get verbs.

Public Info Pages

The public info pages are already available and should stay secondary to the verb utility. /faq, /about, /privacy, /terms, and /cookies use a simple article layout with the public header actions: language pair, log in, and sign up. /contact_us opens the contact form with the same public shell and spam-prevention fields. No contact form submission was tested.

Current gaps:

Public information pages are not visually integrated with the richer authenticated surfaces.
Legal and FAQ pages are readable but dense, and they need a stronger shared article/form shell for mobile.
The current contact route is /contact_us; the target sitemap can keep it or add /contact as a friendlier alias.

Design implication: preserve these pages, but treat them as quiet support/legal surfaces. Claude Design should design a reusable public article/form shell, not a marketing landing page.

The authenticated header currently shows the Immersive mark and a small avatar/default-image menu. Primary authenticated destinations are inside the avatar dropdown and repeated in the footer. The dropdown includes Admin, Profile, Account settings, Grammar, Decks, Documents, and Log out.

User direction: the current top-right dropdown can be replaced. Do not preserve the avatar dropdown as a design constraint.

Current mismatch with target navigation:

The current authenticated navigation is hidden in avatar/footer links rather than exposed as five persistent primary tabs.
Grammar appears as a menu item, but it does not yet have the first-class level/area workspace required by the redesign.
Verbs remain public-root oriented rather than having a signed-in primary-tab workspace.
Footer navigation does too much work for authenticated users.
Detail pages often become modal-like full-page views with close buttons, which can feel detached from the app shell.

Design implication: authenticated web needs an explicit five-tab shell. Replace the current dropdown with a clearer navigation/account pattern; Decks, Documents, Profile, Grammar, and Verbs become the main navigation, while admin/session/account actions can move to a smaller secondary control.

Onboarding

/user_informations/new is a pre-signup language capture page with two native selects: “I speak” and “I want to learn.” It currently shows English, Spanish, French, Italian, and Portuguese. Catalan is not visible in this browser flow, and there is no level selection, tile/button treatment, “more languages coming soon” affordance, or optional subscription step.

Design implication: keep this route’s intent but redesign it as the first onboarding step with the six requested languages, tile/button selection, level capture, and post-account continuation.

Decks

The /decks index already follows the list-row direction: deck title, subtitle, bookmark action, and card count. The filter button reveals a top search/filter bar. This is a good basis for the Decks tab.

Current gaps:

No folders, nested grouping, due/new/learning rollups, prebuilt library, or obvious “review due now” grouping are visible.
The deck Study button is wired up as a prominent start-review CTA on the deck show page (#307).

Design implication: Decks should preserve the list-row pattern but add folder rows, due-count summaries, prominent review entry, and a library/prebuilt path.

Review Sessions

Deck review is the closest current UI to the requested flashcard foundation. /decks/:id/review supports Read, Write, Listen, and Speak modes. The review screen has a focused prompt, an answer/reveal or input area depending on mode, FSRS-style Again/Hard/Good/Easy buttons with interval labels, and small due/new/learning stats.

Current gaps:

Mode tabs are plain text links and need active state/segmented-control treatment.
There is no contextual chat/explanation entry point.
Review statistics are present but not integrated into a session summary or persistent history.
Grading buttons are visible before answer submission/reveal in some modes, which should be reconsidered in the final interaction design.

Design implication: keep the existing review mechanics and improve the shell, controls, chat affordance, and session lifecycle.

Grammar

The /grammar index is a compact list of grammar notes with bookmark actions, categories, CEFR badges, filter button, and pagination. It is already close to the list-row design system.

Grammar note detail has the core bilingual feature requested in the brief: the note can be read in the fluent language and toggled into the target language. Related notes are visible. The content itself is useful and direct.

Current gaps:

No progress chart, mastery rating, effort count, due indicator, weak-state marker, or recommendation flow is visible.
No exercises are visible on the sampled note, matching the current data snapshot where grammar exercises are empty.
The note metadata appears as wide full-width blue bars instead of compact badges.
The language toggle appears after the note content, which makes target/fluent switching less discoverable.

Design implication: grammar is content-rich but practice/progress-poor. The redesign should keep note browsing and bilingual reading, then add progress, generated/associated exercises, FSRS cards, and a stronger note header.

Documents

The /documents index uses the same list-row pattern as decks, with document title, level, bookmark, and word count. It is a solid base for the Documents tab.

Document detail has a reader with Sentences and Words tabs, word count, bookmark, edit, and close controls. The sentences view is already chunked for interaction. The words view exposes individual word tokens, but the sampled page also displayed literal <br> text and awkward token spacing, which should be corrected.

Current gaps:

No folders, file management, upload/import, OCR, dictation, writing prompt, correction, or coaching surface is visible.
Reader controls for translate/listen/chat are not presented as a clear toolbar.
Document interaction actions may call external services, so they need explicit privacy-aware handling and ownership checks before expansion.

Design implication: Documents should preserve the current reader foundation, then add a real file manager, import/upload flows, sentence/word toolbars, dictation, writing correction, vocabulary capture, and coach entry points.

Verbs

Verb search, verb detail, and conjugation detail are already strong public-first surfaces. The verb detail page shows nominal forms, mood buttons, conjugation groups, and audio controls. Conjugation detail shows the selected form, verb/mood/tense metadata, an example sentence, audio, and translation.

Current gaps:

Signed-in actions such as “add this verb/tense/conjugation to a deck” are not prominent.
CEFR level or learning-path context is not visible.
The verb detail page is useful but dense; it needs better grouping and action hierarchy for repeated study use.

Design implication: preserve verbs as the signed-out utility and add signed-in conversion actions into cards/decks/progress.

Profile and Account

The current /profile page is a sparse profile card: avatar, name, location, fluent language, and target language, with edit and close controls. Account settings is a separate page with a small left navigation for account settings, edit profile, and password. Edit profile currently lives at /users/:id/edit, while change password uses Devise at /users/edit.

Current gaps:

No Profile primary tab shell.
No cross-domain progress map, activity graph, peer evaluation/QR flow, vocabulary list, chat history, teacher permissions, or billing/subscription grouping.
Account and profile editing are separate from the requested profile command center.

Design implication: Profile needs the largest product redesign. It should become the learner command center while account settings remain a secondary area.

Existing UI Implications

The current app already has the right raw materials: public verbs, list-row indexes, deck reviews with FSRS buttons, grammar notes with bilingual reading, and document segmentation. The redesign should be an extension of those strengths, not a visual reset.

The largest gaps are product flow and surfacing:

Signed-in users still land on the public verb page.
Authenticated primary navigation is hidden in avatar/footer links.
Onboarding is pre-signup only and incomplete for the requested six-language/level/subscription flow.
Decks lack folders, library, due summaries, and strong review entry.
Grammar lacks progress and exercises-as-cards.
Documents lack file management, upload/import, dictation, writing, and clear sentence/word tools.
Profile lacks the requested progress/activity/evaluation/vocabulary/chat/permissions surfaces.
Chat is not visible in the browser flows.
Icon-only controls need accessible labels audited across the app.

Product North Star

EuRom5 (Hoepli 2011, from Claire Blanche-Benveniste’s EU-funded EuRom4 line of research; ref_2010_EuRom5_def.pdf attached to #280, with sample chapters scanned and reviewed in detail on the EuRom5 source in the research knowledge base - admin: Knowledge Base > Sources, SLA research domain - per #407, moved there in #540) is a comprehension-only intercomprehension method for five Romance languages (Catalan, Spanish, French, Italian, Portuguese) — the source of Immersive’s “Bridge Method” positioning term. It explicitly separates two competencies — comprehension (reading/listening) and production (speaking/writing) — and trains only the first, on the premise that a learner can read/understand a related-but-unknown language far sooner than they can speak or write it, by leveraging transparency with a language (or languages) they already know plus context; its published result is autonomous newspaper reading (~B1–B2 receptive) in about 40 guided hours. Each EuRom5 lesson pairs a real short text in one target language with: a five-language parallel title (orientation before reading), line numbers (for cross-reference), grammar-comparison callouts showing the same construction across all five languages side by side (e.g. possessives: CA les seves / ES sus / FR ses / IT le sue / PT as suas), sentence-decomposition diagrams for parsing hard constructions, and a line-referenced lexical equivalence table. It does not include English, and it does not do spaced repetition or production practice — both are Immersive’s own additions, not EuRom5’s.

The canonical adaptation of the method into Immersive’s product — the aid taxonomy, the relative-opacity principle, scaffolding fade, the two approaches (target-focus bridge hints now, an intercomprehension reading mode later), and the language-model requirements — is docs/features/bridge_method.md; the per-finding source detail is on the EuRom5 source in the research knowledge base (admin: Knowledge Base > Sources, SLA research domain; #540).

Immersive’s north star: help a learner acquire a new Bridge language faster by making explicit, structural use of the one or more Bridge languages they already know — rather than teaching each language as if in isolation, which is what a generic SRS/course app does regardless of what else the learner already knows. The six Bridge languages are English, Spanish, French, Italian, Portuguese, and Catalan (en, es, fr, it, pt, ca) — English included for its large Latinate/French-derived vocabulary layer (cognate recognition works from English into the Romance languages too: important, possible, restaurant are near-identical across all six), not because it’s part of EuRom5 itself.

Immersive is not a re-implementation of EuRom5 — it adapts the underlying insight (known-language transfer as a first-class, visible mechanism) into a spaced-repetition, production-capable product:

Encounter language — in grammar, verbs, documents, writing, conversation, or imported material — annotated against the learner’s known Bridge language(s) wherever it meaningfully speeds comprehension, following the EuRom5 patterns below.
Convert repeatable learning moments into flashcards or flashcard-like review items, including contrastive ones (e.g. “this construction, the way you’d already recognize it from French”).
Schedule those items with FSRS.
Roll the review data into understandable progress by CEFR level, skill, vocabulary, document, and deck.
Recommend the next useful action while preserving full user control.

Known technical gap this creates: users.fluent_language (see Current-State Codebase Summary) is a single string column — the data model currently assumes a learner has exactly one known language, not “one or more Bridge languages.” Sean’s own dogfooding account is a live example of the gap (fluent in English and French, but the product can only record one). The deep EuRom5 review (#407) raised this from “someday” to prerequisite: EuRom5’s aids are a printed superset that teachers filter per learner L1, and Immersive’s equivalent — computing which items are opaque for this learner — needs the full known-language set as input. The scoped direction (per #407 discussion, tracked in #410): keep target_language and fluent_language as they are, and add user_languages rows per (user, Bridge language) with level a1…c2/native as the knowledge model the aid engine reads. The single column stays a presentation preference; the rows carry the knowledge.

EuRom5-Informed Contrastive Patterns

Concrete component patterns pulled directly from the EuRom5 diagrams, feeding the Component Inventory below and the Claude Design Brief:

Cross-language equivalence table: a compact, line- or term-referenced table showing the same word/phrase across the learner’s known Bridge language(s) and the target — the EuRom5 lexical equivalence table, adapted to whatever known languages a given user actually has (not always all six).
Grammar comparison callout: a small inline box showing one grammatical construction (a tense, a pronoun, a negation pattern) across multiple Bridge languages side by side — the EuRom5 grammar-box pattern, directly usable in Grammar notes and in Documents’ word/sentence annotations.
Sentence decomposition diagram: a lightweight S/V/O (or equivalent) breakdown of a hard sentence, for parsing support — most valuable in Documents’ reader and in Grammar notes with complex example sentences.
Annotated line-numbered reading: line numbers alongside a reading passage so callouts/tables can reference specific lines, the way EuRom5’s own lessons do — a refinement of the existing Documents sentence/word click interaction, not a replacement for it.

These are additive to the existing target/fluent toggle already used in Grammar notes, not a replacement for it — the toggle remains for full note translation; these patterns are for targeted, in-context comparison at the word/construction level.

The #407 deep read of the EuRom5 sample volumes confirmed all four patterns and added a second layer — the inline aid classes that make up the rest of EuRom5’s apparatus (full taxonomy and principles in bridge_method.md; source detail on the EuRom5 source in the research knowledge base (admin: Knowledge Base > Sources, SLA research domain; #540)):

Progressive disclosure before translation (EuRom5’s “phantom word” empty-box mark): the first reveal step for an inferable word is “guessable from context — try it,” with the translation behind a second step. Also the seed of an inference card template (document.word.inference.v1).
Skip markers (“effacée”): spans the reader can safely skip and infer from surrounding context — an aid whose message is “you don’t need help here.”
Listen hints: word-level audio affordances where the sound is more transparent than the spelling; more broadly, synchronized listen-while-reading as a comprehension aid (prosody segments syntax), not just playback.
Morphology decomposition: splitting a token into recognizable parts mapped to known-language cognates (storielle = storia + -elle), including vertical morpheme alignment across languages (imperfect endings -avam/-aban/-aven/-avano/-aient).
Title orientation: a fluent-language title gloss shown before reading, priming global comprehension the way EuRom5’s five-language title row does.
Grammar cross-refs: EuRom5’s [§n] marks — reader annotations linking into a contrastive “grammar of reading” layer in Grammar.

Three principles govern all of these (argued in bridge_method.md): aids are filtered by relative opacity against the learner’s actual known languages, not emitted uniformly; aid density fades as the learner’s demonstrated receptive level rises (EuRom5 tranche A is heavily scaffolded, tranche C sparse); and the reader must never demand exhaustive word-by-word translation — global comprehension with a right to approximation is the success state.

Feature Design

Decks

Decks are the repeatable review workspace. They contain scheduled cards, due/new/learning summaries, folder organization, review entry points, and Anki export for user-created decks. System decks and prebuilt Immersive assets are owned by User::IMMERSIVE_USER_ID = 1, not by nil, and should not be exportable to Anki unless explicitly copied into a user’s editable deck. User-created decks should be exportable to Anki.

Decks should feel close to Anki in usefulness but more integrated with Immersive’s language sources. Cards can originate from grammar exercises, verbs, documents, writing corrections, vocabulary saves, or manual creation. The Decks tab should make the next review action obvious without hiding deck organization or card management.

Grammar

Grammar is a first-class workspace organized by CEFR level and grammar area. A learner can browse notes, read in the target language, reveal fluent-language translation/explanation, practice with dropdown/typed/multiple-choice cards, and see progress by note/category/level. Grammar progress also appears in Profile as part of the cross-domain progress map.

Grammar also gains a contrastive “grammar of reading” layer (EuRom5 §2.2, scoped in its own #280 sub-issue): receptive-focused comparison notes — one construction across the learner’s known Bridge languages and the target — selected by frequency-in-real-texts × observed reading difficulty, and targeted by cross-refs from Documents reader annotations (EuRom5’s [§n] pattern). The shipped grammar-comparison callout is the display primitive. The existing 1,913 grammar notes need a Bridge Method impact review (own sub-issue): which notes gain contrastive callouts, which are contrastive in nature already, and how the layer coexists with the target/fluent toggle. The content shape is finalized after the book’s grammar section is scanned (grammar-of-reading chapter summary on the EuRom5 source in the research knowledge base (admin: Knowledge Base > Sources, SLA research domain; #540)).

Every grammar exercise should become a card or card-source candidate. The review UI should be template-driven so a grammar card can ask for a dropdown choice, typed blank, multiple choice, sentence transformation, or explanation without needing a new database subclass for every format.

Documents

Documents have two primary modes:

Show mode: reading existing target-language material.
Edit mode: writing, editing, importing, and cleaning target-language text.

Documents can be created by typing/pasting text, uploading a PDF, uploading a plain text file, uploading an image/photo, or scanning paper from the mobile app through the document-scanner bridge component. PDF/image/scanner sources are processed and cleaned into canonical plain text. The original source file remains attached for audit/reprocessing, but language features use the cleaned text.

Show mode:

Display the document as readable pages or a continuous reading surface.
Preserve basic formatting where available: headings, paragraph breaks, bold, italic, and underline.
Let the learner switch between sentence mode and word mode.
Click/tap a sentence or word to reveal fluent-language translation — with the EuRom5-informed progressive-disclosure step first where the word is inferable (see “EuRom5-Informed Contrastive Patterns”): an inference nudge, then the translation (calque and/or sense gloss).
Carry the wider comprehension-aid layer (skip markers, listen hints, morphology decomposition, title orientation, grammar cross-refs) as annotations keyed to the reader’s line numbers, filtered by the learner’s known languages and fading with level — scoped in its own #280 sub-issue, rendered through the annotated line-numbered reading component.
Click/tap again or use a play control to hear audio.
Save words, sentences, or phrases into vocabulary/decks.
Open contextual chat with selected word, sentence, paragraph, or correction context.
Use “Read to me” for slow listening, sentence-by-sentence playback, key-word repeats, pause/resume, and adjustable speed.
Let the learner choose the voice from the document view. The selected voice is saved as the user’s default voice for that target language and is also manageable from Profile/account preferences.

Edit mode:

Provide a focused writing surface for target-language work.
Offer optional prompts based on recent study, weak grammar, vocabulary, level, or a selected document.
Allow a learner to submit text for correction.
Show corrections inline, with explanations and alternatives.
Track edit history and allow the user to view, compare, and restore prior versions.
After correction, offer to create review cards from mistakes, corrected sentences, useful phrases, or vocabulary.

Prompt presentation:

In a new writing document, show a compact prompt card above the editor or in the right panel.
The card includes the prompt, target length, focus areas, and actions: Use prompt, Regenerate, Make easier, Make harder, Dismiss.
The prompt should be optional. Users can always write their own text.

Example writing prompts:

“Write 120-160 words about a recent meal. Use the past tense and include five food words from your vocabulary list.”
“Describe your weekend plans using the near future. Try to use aller, faire, and voir.”
“Rewrite this paragraph for a friend. Make it more natural and focus on adjective agreement.”
“Write a short message to a teacher asking for help. Use a polite/formal tone.”

Correction alternatives:

Present alternatives at the sentence/paragraph level, not as a detached report.
Use compact chips or tabs for Natural, Simpler, More formal, and More casual.
Each alternative shows the rewritten sentence, a short explanation, and actions: Replace, Insert below, Explain, Create card.
Desktop uses a right-side feedback panel; mobile uses a bottom sheet that can expand to full screen.

Markdown and rich text:

Markdown or a constrained markdown-like format may be used for authoring, inspired by Writebook’s markdown-backed editing approach.
Headings, bold, and italic map naturally to markdown. Underline should be represented as a deliberately allowed custom mark or sanitized inline HTML because standard markdown does not define underline.
Markdown must not be the final reader contract. The canonical processing layer remains plain text with sentence and word records.
Show mode should render through an Immersive-owned Documents::ReaderRenderer that preserves allowed formatting while wrapping text tokens with data-document-word-id and data-document-sentence-id.
JavaScript then handles word mode, sentence mode, highlighting, translation reveal, audio playback, vocabulary save, and chat handoff.
Avoid a pure browser post-processing strategy where raw markdown HTML is rendered first and then words are wrapped with JavaScript. That is brittle for formatting, punctuation, selections, Turbo updates, and mobile taps.

Verbs

Verbs remain the public wedge and become a signed-in workspace. The signed-out root stays a verb conjugator. Signed-in users can save verbs, listen to forms, view examples, generate missing examples, create verb decks, and review weak forms.

The Verbs tab should feel utilitarian and fast: search, open verb, inspect tense/mood/person groups, listen, view examples, and turn useful material into deck cards.

Verbs also gains a cross-language conjugation comparison view (own #280 sub-issue): the same tense/person aligned vertically across the learner’s known Bridge languages and the target — EuRom5’s morpheme-alignment pattern (imperfect endings -avam/-aban/-aven/-avano/-aient) applied to data Immersive already holds in all six languages. Language columns follow the canonical continuum order PT–ES–CA–IT–FR–EN (see bridge_method.md).

Profile

Profile is the learner command center, not the only place where learning happens. It summarizes progress and gives cross-domain next actions.

Profile subareas:

Progress map: grammar, verbs, decks, documents, vocabulary, writing, due/weak/mastered states.
Activity graph: GitHub-style study activity by day and event type.
Evaluate: show QR/barcode, scan another user, give/view grades.
Vocabulary: collected from documents, grammar tests, writing corrections, and cards.
Chat history: resume contextual and general chats.
Teachers/permissions: grant scoped access to progress or lists.
Account/profile settings: name, avatar, languages, default document voice, password, billing.

Design note from the #407 EuRom5 review (per Q5 decision, no separate issue yet): progress should be able to show receptive and productive competence as separate axes — EuRom5 grounds this in the CEFR’s partial competences, and a Bridge Method learner may legitimately read at B2 while producing at A2. Reading/listening evidence (documents read, listening comprehension, recognition reviews) and production evidence (writing corrections, typed/spoken reviews) should not collapse into one blended level. This also pairs with the languages-known capture: Profile is where user_languages (which Bridge languages, at what level A1–C2/native) get displayed and edited once the bridge-language data model ships.

Chat

Chat should be contextual everywhere without visually dominating the app. Review screens, grammar exercises, document reader, writing feedback, and profile/global actions all open the same underlying chat system with different context snapshots.

Desktop behavior:

A compact chat dock or button opens a small panel.
The panel can expand into a sliding right-side chat.
The chat context includes the current page, selected text, source record, answer attempt, correction, language pair, and relevant weak areas.

Mobile behavior:

Use a chat pill or toolbar action rather than a side panel.
Open chat as a bottom sheet that can expand to full screen.
Keep selected sentence/word/correction context visible at the top of the sheet.
Returning from chat should restore scroll position and the selected document/review state.

Onboarding

Onboarding happens after account creation. Users choose target language, fluent language, starting level, and optionally see subscription. They land in Profile progress with a concrete starter action, not a marketing page.

UX Design

The UX should make Immersive feel like one coherent learning workspace even though it includes several domains. Primary navigation answers “where am I studying?”, local toolbars answer “what can I do here?”, and contextual chat answers “help me understand this exact thing.” The app should avoid a course-like funnel and instead make the next useful action obvious while preserving learner control.

Signed Out

The signed-out app is a useful public verb conjugator, not a marketing landing page.

Root should continue to present the verb lookup/conjugator experience, subject to route review.
Public pages like FAQ, about, contact, legal, and Anki/public decks remain secondary.
Sign up/log in are available from the public shell.
Public verb pages should preview the broader product through useful actions: listen, view examples, add to deck after sign-up, and explore language/tense.

First Account Flow

After account creation, users go through onboarding before landing in the profile area.

Choose target language from en, es, fr, it, pt, ca.
Choose fluent language from the same language list.
Choose approximate level or “I am learning from the beginning”.
Optional “more languages coming soon” link or panel.
Optional subscription page.
Land on the Profile progress map.

Authenticated Primary Tabs

Use five primary tabs across mobile and desktop:

Decks: decks, deck browser, folders, reviews, library/prebuilt decks.
Documents: document files, folders, reader, uploads, writing, dictation.
Profile: progress map, activity graph, evaluate/grades, vocabulary, chat history, teacher permissions, account, billing.
Grammar: grammar by CEFR level and area, note reading, exercises, grammar review, mastery states.
Verbs: conjugator/search, conjugation tables, audio/examples, signed-in deck creation, weak-verb review paths.

Desktop representation:

Use a quiet persistent top product nav.
Keep the five primary tabs persistent and obvious: Decks, Documents, Profile, Grammar, Verbs.
The current top-right avatar dropdown may be removed or fully replaced.
Chat and account/settings are right-side utilities, not primary destinations.
Profile subareas stay inside Profile; Grammar and Verbs are no longer hidden under Profile or contextual links.

Mobile representation:

Use five bottom tabs for Decks, Documents, Profile, Grammar, and Verbs in Hotwire Native/Turbo Native and mobile web.
Keep contextual chat available inside test/document surfaces.
Profile remembers the last used sub-tab.

Design System Direction

Preserve and extend the current system. The visual register to aim for is the one confirmed against the shipped bridge components — subtle, intellectual, academic; see “Confirmed visual register” under Product Direction and the live reference at /admin/design_system/bridge.

Custom CSS only. No Bootstrap, Tailwind, React, or Vue.
Rails HTML first, then Turbo Frames/Streams, then Stimulus for interaction.
Index pages use list rows, not card grids.
Components should be dense, readable, mobile-first, and 37signals-inspired.
Use existing semantic tokens and add only the minimum needed for progress states, activity heatmaps, review feedback, and grouped navigation.
Use system fonts. No custom font downloads.
All hardcoded UI strings go through locales.
Dark mode redefines only the raw --lch-* primitives; semantic tokens are single-sourced.
Focus states use --focus-ring and focus-visible.

New or extended components:

Progress bar: thin, semantic color by state.
Progress ring: small SVG/canvas component for level, deck, and note mastery.
Proficiency dot: inline table/list status marker.
Activity heatmap: GitHub-style grid for profile activity.
Segmented control: language view, profile sub-tabs, document mode, quiz filters.
Review grade buttons: Again, Hard, Good, Easy with interval labels.
List row variants: folder row, deck row, grammar category row, document row, vocabulary row, review history row.
Chat entry button/panel: contextual, compact, history-aware.
Cross-language equivalence table, grammar comparison callout, sentence decomposition diagram, annotated line-numbered reading: the four EuRom5-informed contrastive patterns (see “Product North Star”).

Technical System Design

Design principle: reuse the current Rails learning substrate and extend it carefully. Decks use the existing Deck model directly. Card, Review, Reviews::FsrsScheduler, StudyEvent, and UserAbility remain the core learning engine.

Architecture Decisions

Keep Rails HTML/Turbo/Stimulus as the application architecture.
Keep Deck as the persistent model and product language.
Keep Card as the scheduled memory item and add a template-driven testing layer instead of expanding STI for every new card shape.
Keep Review#reviewable polymorphism, but make flashcard reviews use Card consistently.
review_sessions and card_sources exist (#293, see Core Data Model) - wire card_sources into grammar/document/verb card generation before adding new review surfaces that need source links.
Add card template keys/classes so prompt rendering, accepted answers, audio targets, hints, and answer evaluation can vary without schema churn.
Treat StudyEvent as the raw event stream and UserAbility as the resource-level rollup layer.
Treat profile charts and recommendations as cached/queryable projections over reviews, study events, user abilities, and grammar masteries.
Extend current chats and messages instead of creating a parallel chat store.
Add Pundit checks before expanding API/action surfaces that currently authenticate but do not fully authorize ownership.
Localize all new text and preserve current CSS conventions.

Current code to avoid building on until cleaned up:

Legacy service names under app/services/cards/* still reference pre-Deck naming, CardList, CardView, SentenceQuizCard, ExerciseCard, or QuizCard, none of which are present in the current schema.
Decks::DecksController#create_content references Decks::Content::CreateService, which is not present. Use the working deck/card services as the base and normalize this path before adding new creation flows.

Core Data Model

Use these existing tables as the foundation:

Area	Existing Models/Tables	Role
Decks/cards	`decks`, `cards`	User and public decks, card queue, FSRS fields.
Reviews	`reviews`	Individual graded attempts and FSRS before/after data.
Events/progress	`study_events`, `user_abilities`	Activity stream, modality ability, due/weak resources.
Grammar	`grammar_notes`, `grammar_categories`, `grammar_exercises`, `learning_objectives`, `curricula`	CEFR content, note translations, practice source material.
Documents	`documents`, `document_sentences`, `document_words`	Reader, segmentation, translation/audio targets.
Verbs	`verb_lemmas`, `conjugations`, `tenses`, `sentences`, `sentence_conjugations`	Public conjugator, examples, verb cards.
User/profile	`users`, `bookmarks`, `subscriptions`	Language pair, account, public newsletter/subscription capture.
Chat	`chats`, `messages`, `tool_calls`, `models`	RubyLLM chat persistence primitives.

Add or extend these tables:

Change	Purpose
`DeckFolder` (`app/models/decks/deck_folder.rb`, `deck_folders` table, `belongs_to :user`, `has_many :decks`) plus `decks.folder_id`. Supersedes the shared generic `Folder` model originally planned here.	Decks folder organization, already live.
`DocumentFolder` (#286) is not a flat mirror of `DeckFolder` — it’s self-referential (`belongs_to :parent, class_name: "DocumentFolder"`, `has_many :children`), supporting arbitrary nesting, with cycle-prevention validation and a `breadcrumb_path`/`ancestors` helper. `folder_id` on `documents` is nullable (root-level docs allowed).	This is the right call for Documents specifically, not a deviation to fix: the original request asked for Documents folders “like Google docs,” which is inherently hierarchical — unlike Decks, which reasonably stays flat (Anki’s own deck-grouping convention has no real nesting concept either). Keep Decks and Documents folders as two genuinely different, independently-justified shapes rather than forcing one pattern onto both. The old `folders` table remains unused and can be dropped.
Extend `documents` with source/import fields: `source_kind`, `import_status`, `import_error`, `content_plain_text`, `content_markdown`, optional cached `content_html`, and `source_file` attachment.	Support typed, pasted, uploaded, OCR, and scanned documents while keeping plain text as the processing source of truth.
Create `document_revisions` with document, actor, snapshot text/markdown, reason, source kind, and metadata.	User-facing edit history, AI correction history, import cleanup history, compare, and restore.
Create `user_voice_preferences` or equivalent user settings keyed by language/provider/voice.	Save document “Read to me” default voice from the reader and expose it in Profile/account settings.
Optionally create `audio_assets` keyed by source record, language, voice, provider, and speaking rate.	Avoid one random voice attachment per word/sentence and support user-selected voice playback.
Shipped (#293): `review_sessions`, with `review_session_id` on `reviews`; `Decks::ReviewsController` actually creates/reuses sessions via `ReviewSession.find_or_create_active`.	Group card attempts, session stats, review history, and profile activity.
Shipped (#293): `card_sources` with `card_id`, polymorphic `source`, `source_role`, and `metadata`. Not yet populated outside decks - still needs the `Cards::SourceLinker` service below wired into grammar/document/verb card generation.	Link cards to grammar exercises, grammar notes, document words/sentences, vocabulary entries, conjugations, writing feedback, or generated prompts.
Add `template_key`, `template_version`, `prompt_payload`, and `answer_payload` to `cards`, or create a `card_templates`/`card_payloads` table if payload size grows.	Let one scheduled card test many content shapes without adding a new subclass or column set for every template.
Extend `grammar_exercises.exercise_type` values.	Support dropdown, typed blank, multiple choice, correction, and translation while preserving existing `free_text` and `multiple_choice`.
Create `grammar_masteries`.	Cache per-user grammar note rating, effort count, mastery score, due count, weak flag, last studied, and next due.
Create `grammar_note_prerequisites`.	Optional dependency graph for grammar recommendations.
Create `vocabulary_entries`.	User vocabulary list gathered from documents, grammar tests, cards, and manual saves.
Create `writing_submissions`.	Store writing prompts, submitted text/photo attachment, correction JSON, alternatives, CEFR grade, and source weak areas.
Create `peer_grades`.	Store grader, recipient, ratings, comments, visibility, and QR/evaluation flow results.
Create `user_access_grants`.	Teacher/viewer permissions by scope, target language, and expiry/revocation.
Extend `chats` with `user_id`, `context_type`, `context_id`, `context_snapshot`, `title`, and `last_message_at`.	Chat everywhere with owned history and scoped context.
Add onboarding fields to `users`.	`starting_level`, `onboarding_completed_at`, optional goal/subscription prompt timestamps.
Optionally create `user_activity_days`.	Cached GitHub-style activity graph if direct `study_events` queries become too expensive.

Do not add separate document_segments yet. document_sentences and document_words already do that job and should be extended only when OCR/extraction needs more positional metadata.

Review and FSRS Pipeline

Current review flow:

Deck#next_card_for_review selects the next due card.
Card#record_review! computes FSRS state through Reviews::FsrsScheduler, creates a Review, and updates the card.
Decks::ReviewsController handles modes and answer grading.

Target review flow:

Reviews::SessionStarter finds or creates an active review_session for the user, source, deck, and mode.
Reviews::QueueBuilder returns the next authorized card for the user, deck/source, mode, due state, and daily limits.
Reviews::AnswerEvaluator delegates to the card template for accepted answers, partial credit, hints, pronunciation checks, and writing graders.
Reviews::Recorder calls Card#record_review!, assigns review_session_id, logs StudyEvent, updates UserAbility, and marks dependent rollups stale.
Reviews::SessionSummarizer updates counts and completion stats for profile/history.

Security hardening required before broadening review:

Move Decks::ReviewsController under AuthorizedController or explicitly call authorize @deck.
In submit_review, load the card through @deck.cards.find(params[:card_id]) so a user cannot submit a review for a card outside the authorized deck.
Localize hardcoded review notices and errors.

Decks

Decks should keep Deck and Card as the storage layer.

Implementation changes:

Folder organization already shipped via DeckFolder and required decks.folder_id (see Core Data Model). Due/new/learning stat columns and folder grouping already shipped directly in Decks::DecksController/views rather than through the service objects below — treat the items after this one as a refactor of working code, not greenfield.
Add Decks::DueSummary to aggregate new/learning/review/due counts without expensive repeated pluck.
Add Decks::FolderSummary for recursive folder row counts.
Add Decks::ReviewLauncher to centralize mode availability and start-review CTAs.
Use Deck.publicly_visible, copied_from, and User::IMMERSIVE_USER_ID for prebuilt/system decks; keep deck_subscriptions out of the P0+P1 design unless copying prebuilt decks creates too much storage churn.
Keep Anki export through current Decks::Anki::* services for user-created or user-owned copied decks. Prebuilt/system Immersive decks are not directly exportable.

Card creation strategy:

Reuse existing WordCard, SentenceCard, VerbCard, and NumberCard compatibility paths where they already work.
Do not keep adding STI subclasses as the default extension mechanism.
Use template keys for new card experiences such as grammar.dropdown.v1, grammar.cloze.v1, verb.conjugation.production.v1, sentence.translation.recall.v1, document.word.recognition.v1, dictation.sentence.v1, and writing.correction.choice.v1.
Add Ruby template classes that can render prompts, normalize answers, evaluate attempts, declare audio targets, expose hints, and list supported modes.
Always write a card_sources row for generated cards so progress can roll back to grammar notes, documents, verbs, vocabulary, or writing feedback.

Grammar

Grammar progress should be built from current GrammarNote, GrammarCategory, GrammarExercise, LearningObjective, and Curriculum.

Implementation changes:

Make /grammar a first-class primary tab organized by CEFR level and grammar area.
Keep the Profile progress map as the cross-domain progress surface, while Grammar owns day-to-day grammar browsing, notes, exercises, and grammar review.
Generate cards from grammar_exercises with Grammar::CardGenerator.
Link each generated card to both the GrammarExercise and parent GrammarNote through card_sources.
Add Grammar::MasteryRecalculator to update grammar_masteries after relevant reviews.
Add Grammar::ProgressQuery for the profile chart by level/category/note.
Add Grammar::RecommendationService for due, weak, next-level, prerequisite-ready, and category-balanced topics.
Add Grammar::ExerciseSeeder or import task to create exercises, because current local data has 1,913 grammar notes and 0 exercises.

Mastery calculation:

New/unstudied notes score 0.
Card-level score should combine FSRS state, recent ease buttons, reps, lapses, and due state.
Note score averages linked exercise cards. Effort (time spent, reps, session count) feeds mastery scoring but must also be surfaced as its own separately displayed number in Profile — see “Effort as a first-class metric” below. Do not fold effort into a single blended mastery score; a user who has put in real work should be able to see that even in a week where the mastery number hasn’t moved.
Category and level scores are query rollups from grammar_masteries.
Store both numeric score and user-facing rating label for stable charts.

Effort as a first-class metric (per docs/features/immersive_business_plan.md, “Effort Tracking, Not Just Mastery”): mastery answers “how well is this known”; effort answers “how much work has gone in,” and both should be visible independently on Profile. Card#record_review! calls StudyEventLogger on every review (#293), converting the already-existing client-timed reviews.answer_time (seconds, captured by review_timer_controller.js) into study_events.review_duration_ms. What remains is surfacing this in Profile: roll study_events up into user_activity_days (minutes/seconds column already anticipated there) and show it as a distinct summary, not folded into mastery. Track an “effort streak” (did any effortful study happen today) separately from any accuracy-based streak, and never let a wrong answer read as breaking it — punishing mistakes on the effort axis contradicts the point of tracking effort at all.

Mastery thresholds:

Score	Label	UI State
0%	Not started	Grey
1-24%	Beginner	Red
25-49%	Developing	Amber
50-74%	Intermediate	Yellow/neutral
75-89%	Proficient	Light green
90-100%	Fluent	Green

Documents and Writing

Documents already have a useful processing chain: Resources::Documents::ProcessJob segments sentences, tokenizes words, evaluates level, and counts words.

Implementation changes:

DocumentFolder (PR #286) — nested, not flat, unlike DeckFolder; see the Core Data Model note on why that’s the correct shape for Documents specifically.
Add ActiveStorage source_file to Document plus import status/source kind metadata for PDF/image/text/photo/scanner uploads.
Add Documents::Importer for file intake, text extraction, OCR handoff, cleanup, and canonical text creation.
Add OCR jobs for image/photo/PDF/scanned pages.
Keep document_sentences and document_words as the reader segment tables, but add stable offsets or token ranges if needed for formatted rendering.
Add content_plain_text as the canonical processing field. Keep existing content as compatibility during migration or rename deliberately after data migration.
Add content_markdown or constrained markdown-like storage for edit mode formatting. Cache sanitized HTML only for display/performance.
Add Documents::ReaderRenderer to render allowed formatting while wrapping tokens with sentence/word data attributes.
Add Documents::ContentNormalizer to convert markdown/imported HTML/OCR output into canonical plain text and safe formatting.
Add ownership checks to document sentence/word translation API endpoints; they currently authenticate but load by token id without confirming the current user owns the parent document.
Replace simulated Resources::Documents::CoachService with a real Documents::CoachService wrapper around Chat::ContextBuilder.
Add Documents::DictationPlanner and Writing::CorrectionService.
Add Documents::ReadAloudPlanner for “Read to me” playback, slow rate, sentence pauses, key-word repeats, and voice selection.
Add user voice preferences and expose them from the document toolbar and Profile/account settings.
Add document_revisions for manual edits, import cleanup, AI corrections, restore, and compare history.
Add writing_submissions for typed or photo-uploaded writing, prompts, corrections, alternatives, and CEFR grade.
Add Vocabulary::Collector hooks when a user translates, saves, misses, or reviews document words/sentences.

Markdown/rich text renderer:

Current Immersive already uses kramdown and kramdown-parser-gfm for grammar/curriculum markdown through Markdownable.
Rails includes Action Text/Trix support as a standard Rails feature, but Immersive does not currently use has_rich_text for documents.
Writebook is the strongest local reference: it uses a custom ActionText::Markdown record, a markdown editor toolbar, rendered HTML, plain-text extraction, autosave, and edit history. Immersive should adapt the pattern conceptually, not copy the book-publishing model wholesale.
Use markdown or constrained markdown-like text only as an authoring/editing layer.
Support underline as an explicit constrained mark, not as arbitrary HTML.
Do not render raw markdown HTML as the interactive reader.
The server-side reader renderer should parse the document structure, preserve allowed formatting, and wrap textual tokens with data-document-word-id and data-document-sentence-id.
Stimulus should handle the mode-specific behavior: word tap, sentence tap, sentence highlight, translation reveal, audio playback, vocabulary save, and chat handoff.
This avoids brittle browser-only token wrapping and lets formatted text such as Je suis **tres** content. remain clickable at both word and sentence levels.

Document creation pipeline:

User creates, pastes, uploads, or scans a document.
ActiveStorage keeps the original source when applicable.
Import job extracts text from text/PDF/image/scanner input.
OCR and cleanup normalize the text.
Canonical plain text is saved.
Optional formatting is saved as constrained markdown.
Processing job rebuilds document_sentences and document_words.
Reader renderer displays formatted, sentence/word-aware text.

Writing prompt and correction pipeline:

Writing::PromptBuilder gathers recent study, weak grammar, vocabulary, level, and optional document context.
Edit mode shows a compact prompt card with actions to use, regenerate, simplify, increase difficulty, or dismiss.
User writes or edits text.
Writing::CorrectionService returns structured corrections, explanations, alternatives, CEFR estimate, and suggested card sources.
Feedback is displayed inline and in a side panel/bottom sheet.
User can replace text, insert alternatives, ask chat for explanation, create cards, or save a revision.

Correction alternatives should be represented as structured data, for example:

natural: idiomatic rewrite for the same meaning.
simpler: easier vocabulary and syntax.
formal: more formal register.
casual: more conversational register.

Document privacy:

User files, extracted text, document translations, and uploaded photos should be treated as user-owned private content.
Teacher access must go through user_access_grants.
LLM calls should store enough context for audit/debugging without exposing more user text than needed in logs.

Verbs

The signed-out root remains the public verb conjugator. Signed-in verb actions should feed Decks and progress.

Implementation changes:

Keep VerbLemma, Conjugation, Tense, sentence matching, and existing generation jobs/services.
Add tense_levels only if curriculum needs a stable CEFR mapping for tense/mood/person combinations.
Add Verbs::DeckBuilder to create VerbCard decks from a verb, tense, mood, CEFR slice, or weak conjugation query.
Add Verbs::ExampleCoverageQuery to find conjugations without examples/audio.
Use existing Resources::Conjugations::GenerateSentenceJob and Resources::Conjugations::PrepareSentenceAudioJob patterns for missing examples.
Link generated cards to Conjugation, VerbLemma, and any generated Sentence through card_sources.

Profile, Evaluation, and Permissions

Profile becomes an authenticated learner command center, not the current sparse user show page.

Implementation changes:

Add profile controllers under Users::Profile::* or Profile::* for progress map, activity, evaluate, grades, vocabulary, chat, teachers, permissions, and account links.
Read progress primarily from grammar_masteries, verb/deck/document rollups, review_sessions, study_events, user_abilities, and vocabulary_entries.
Add peer_grades with grader/recipient, skill ratings, comment, visibility, and optional source context.
Add QR/barcode token generation for evaluation; tokens should be short-lived and map to a recipient user.
Add user_access_grants for teacher permissions with scopes such as progress, vocabulary, activity, and documents.
Keep account settings, edit profile, billing, language settings, data export, and Devise password flows secondary to the Profile tab.

Activity graph:

Initially query study_events grouped by user/day.
If the graph becomes slow, cache into user_activity_days with counts for reviews, document interactions, grammar attempts, writing, chat help, and minutes/seconds when available.
Show effort (sessions, reviews, time spent) as a distinct summary alongside the heatmap, not only implied by cell shading — a user should be able to read “18 sessions, 3h42m, 214 reviews this week” directly, independent of the mastery/progress charts elsewhere on Profile.

Chat Everywhere

Current RubyLLM tables exist, but Chat does not yet belong to a user or a context. Extend it rather than replacing it.

Implementation changes:

Add user_id and context columns to chats.
Add Chat::ContextBuilder with inputs: user, route/surface, source record, selected text, current card/review, answer attempt, recent weak areas, and language pair.
Add Chat::Starter to open or reuse a context chat.
Add Chat::Responder to call RubyLLM, persist messages/tool calls, and attach trace metadata.
Add context entry buttons to review cards, grammar notes/exercises, document sentence/word actions, writing feedback, and Profile.
Store a compact context_snapshot so old chats remain understandable after records change.
Desktop chat supports a compact dock, sliding right panel, and full-height reading/writing context.
Mobile chat opens as a bottom sheet that can expand to full screen, preserves selected word/sentence/correction context, and restores the same reader/review state on close.

Onboarding and Subscription

Current onboarding is pre-signup UserInformation stored in session. Keep that as the public signup lead-in, then add a post-account onboarding state.

Implementation changes:

Add starting_level, learning_goal, and onboarding_completed_at to users.
Extend language choices to en, es, fr, it, pt, and ca.
Add onboarding routes for language pair, starting level, optional subscription prompt, and completion.
Update after_sign_in_path_for and registration flow so new users land in onboarding until complete, then /profile/progress.
Current Subscription is a public mailing-list model, not billing. For P0+P1, design the subscription step as optional and non-blocking; a real billing provider model is outside this design scope.

Services and Jobs

Add these service boundaries:

Service	Responsibility
`Reviews::SessionStarter`	Create/reuse active sessions.
`Reviews::QueueBuilder`	Select the next authorized card by source/mode/due state.
`Reviews::Recorder`	Record FSRS review, event, ability, session stats, and stale rollups.
`Cards::TemplateRegistry`	Resolve `template_key` and version to an Immersive-owned Ruby template class.
`Cards::TemplateRenderer`	Render prompts, reveal states, hints, audio targets, and supported modes from card payloads.
`Cards::AnswerEvaluator`	Normalize and grade answers using template-specific rules.
`Cards::SourceLinker`	Create `card_sources` rows.
`Decks::DueSummary`	Aggregate due/new/learning counts.
`Decks::FolderSummary`	Recursive folder summaries.
`Grammar::CardGenerator`	Generate cards from exercises.
`Grammar::MasteryRecalculator`	Update note-level mastery.
`Grammar::ProgressQuery`	Feed grammar views and the Profile progress map.
`Grammar::RecommendationService`	Choose next grammar actions.
`Documents::Importer`	Ingest uploads and extracted text.
`Documents::ContentNormalizer`	Convert imported/OCR/markdown input into canonical plain text and safe formatting.
`Documents::ReaderRenderer`	Render allowed formatting while emitting sentence/word-aware spans for interaction.
`Documents::ReadAloudPlanner`	Build slow read-aloud sequences, voice choice, sentence pauses, and key-word repeats.
`Documents::DictationPlanner`	Build dictation sequence and key-word repeats.
`Documents::RevisionRecorder`	Save, compare, and restore document edit/import/correction revisions.
`Writing::PromptBuilder`	Create writing prompts from weak areas/recent study.
`Writing::CorrectionService`	Correct, grade, and suggest alternatives.
`Vocabulary::Collector`	Create/update vocabulary entries from sources.
`Verbs::DeckBuilder`	Create verb decks/cards from conjugation queries.
`Chat::ContextBuilder`	Build scoped chat context.
`Users::ActivityRollup`	Compute/cached activity graph data.

Background jobs:

Reviews::SessionTimeoutJob
Grammar::MasteryRecalculationJob
Grammar::RecommendationRefreshJob
Documents::ImportJob
Documents::OcrJob
Documents::AudioPreparationJob
Documents::RevisionCompactionJob
Writing::CorrectionJob
Vocabulary::CollectionJob
Verbs::ExampleCoverageJob
Users::ActivityRollupJob

Big-Bang P0+P1 Build Scope

Design P0 and P1 together as one coherent release scope. Claude Design should not create separate visual phases; the goal is a complete product direction for the first serious release, with enough depth for Claude Code to implement iteratively.

In-scope areas:

Foundation hardening (#293): authorization fixes, review_sessions, card_sources, DocumentFolder model (Decks folders already shipped as DeckFolder), localized review strings, and dead service cleanup.
Authenticated shell: five persistent tabs on desktop and mobile: Decks, Documents, Profile, Grammar, Verbs.
Design system first: refine the existing custom CSS tokens, app shell, list rows, buttons, toolbars, segmented controls, progress states, review cards, document tokens, chat drawer/sheet, and settings forms before designing final screens.
Decks: foldered /decks index, due summaries, review launcher, deck detail, review session, session history, user deck Anki export.
Documents: folders, uploads/import/OCR/scanner entry, reader ownership checks, canonical plain text plus constrained formatting, reader renderer, read-aloud voice preferences, dictation, document revisions, writing submissions, corrections, alternatives, vocabulary hooks.
Grammar: first-class tab shell, level/area browsing, exercise generation, grammar cards, mastery cache, progress views, recommendations, grammar chat entry.
Verbs: first-class tab shell, signed-in deck actions, saved/weak verbs, example/audio gap jobs, verb deck builder, tense-level mapping where needed for the designed views.
Profile: progress map, activity graph, vocabulary, peer grading, teacher permissions, chat history, account links, default document voice setting.
Onboarding and account: six-language onboarding, starting level, optional subscription prompt, redirects, profile/account/password/settings patterns.
Mobile native behavior: top-level ios/Immersive/ and android/Immersive/ apps, five native tabs, scanner bridge components, native form/button/search/menu/share/toast/haptic affordances, and web fallbacks.
Public support surfaces: FAQ, about, contact, privacy, terms, cookies using a quiet reusable article/form shell.

Page Flow and Sitemap

Flow principle: make the app feel like one learning workspace. The user should always know whether they are collecting material, studying material, or reviewing progress.

Route Strategy

Keep current working Rails routes where possible: /, /verbs, /decks, /documents, /grammar, /profile, /account_settings, /users/edit, /user_informations/new, and public info routes.
Add user-facing aliases where they improve product language: /contact can alias /contact_us; /profile/progress can become the authenticated landing page.
Keep /decks as the canonical Decks route and product label.
Keep signed-out / as the public verb conjugator.

Global Page Flow

Signed out:

Public user lands on / and can use the verb conjugator immediately.
Verb detail, FAQ, contact, about, legal, login, and signup are secondary public destinations.
Signup starts with language choice, then account creation, then post-account onboarding.

New account:

Choose fluent and target languages.
Choose starting level or “I am learning from the beginning.”
See optional subscription prompt.
Land on /profile/progress.

Returning authenticated user:

Land on /profile/progress, last primary tab, or stored destination.
Use the persistent primary nav: Decks, Documents, Profile, Grammar, Verbs.
Use the Profile progress map as the cross-domain map, then jump into Grammar, Verbs, Decks, or Documents for action.
Reach chat from review/test/document/writing surfaces and from Profile chat history.

Desktop/web:

Use a persistent top app bar.
Left: Immersive mark links to the authenticated default destination.
Center or left-adjacent: five primary tabs: Decks, Documents, Profile, Grammar, Verbs.
Right: compact actions for global chat, account/settings, and log out. The current top-right dropdown is replaceable and should not carry primary navigation.
Profile sub-tabs appear as a sticky secondary row inside Profile.
Decks, Documents, Grammar, and Verbs use local toolbars for search, filters, create/import, review, and folder or area actions.

Mobile/web and Turbo Native:

Use five bottom tabs for Decks, Documents, Profile, Grammar, and Verbs.
Keep page-level actions in a top toolbar.
Use segmented controls for Profile sub-tabs and review/document modes.
Hide footer navigation for authenticated mobile flows.
Keep review sessions and document dictation focused, with minimal surrounding chrome.

Public Sitemap

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/`	Public verb conjugator	Search verb, choose language pair, open conjugation, log in/sign up	`VerbLemma`, `Conjugation`, `Tense`	No verb found: suggest spelling/language and common verbs	Public
`/verbs`	Verb index/search alias	Search/filter verbs	Verb lemmas by language	No results: clear query and show common verbs	Public
`/verbs/:id`	Verb detail	Switch tense/mood, play audio, view examples, create deck after sign-in	Verb lemma, conjugations, examples, audio	Missing examples: offer generated examples for signed-in users	Public, extra actions signed in
`/verbs/:verb_id/conjugations/:id`	Conjugation detail	Listen, view/generate sentence, add to deck	Conjugation, sentence matches, audio	Missing audio/example: show generation state	Public, extra actions signed in
`/anki`	Public deck/Anki page	Browse/download, sign in to copy	Public decks with attachments	No decks: explain coming soon and return to verbs	Public
`/faq`	FAQ	Read, contact	Locale text	Missing locale: fall back to English	Public
`/about`	Product context	Read, sign up	Locale text	Missing locale: fall back to English	Public
`/contact_us`, `/contact`	Contact	Submit message	`Contact`, spam honeypots	Validation errors inline; spam redirects quietly	Public
`/privacy`, `/terms`, `/cookies`	Legal/support articles	Read	Static/legal content	English-only notice where needed	Public
`/users/sign_in`	Login	Log in, reset password	Devise	Bad credentials inline	Public
`/user_informations/new`	Pre-signup language pair	Choose fluent/target language	`UserInformation`, session	Unsupported languages show “coming soon”	Public
`/users/sign_up`	Account creation	Create account	Devise user plus session language pair	Validation errors inline	Public

Onboarding Sitemap

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/onboarding/languages`	Confirm language pair	Pick fluent and target tiles	User language fields	More languages panel shows coming soon	Authenticated, incomplete onboarding
`/onboarding/level`	Establish starting level	Pick CEFR level or beginner option	User starting level	Unsure option defaults recommendations gently	Authenticated
`/onboarding/subscription`	Optional subscription prompt	Continue free, subscribe, skip	User, future billing/subscription state	Billing unavailable: continue free	Authenticated
`/profile/progress`	First landing	Start recommended action	Grammar masteries, recommendations	No progress: show starter path	Authenticated

Authenticated Shell

Primary tabs:

Decks: repeatable review material and folders.
Documents: files, reading, dictation, writing, uploads.
Profile: progress map, activity, evaluation, grades, vocabulary, chat, teachers, permissions, account.
Grammar: levels, areas, notes, exercises, grammar review, grammar recommendations.
Verbs: conjugator, verb tables, audio/examples, saved verbs, deck creation.

Global surfaces:

Surface	Purpose	Behavior
Global chat action	Ask study/coaching questions	Opens latest general chat or starts one with user context.
Account action	Account settings, edit profile, password, billing, logout	Secondary account menu; not primary navigation.
Contextual chat trigger	Explain current task	Appears in reviews, grammar exercises, document reader, writing feedback.
Search/filter	Narrow current list	Local to Decks/Documents/Profile/Grammar/Verbs list surfaces.

Decks Sitemap

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/decks`	Decks index	Review due, open folder/deck, create deck/folder, search/filter, open library	Decks, folders, card counts, due summaries	No decks: show starter deck and library action	Authenticated
`/decks/folders/:id`	Folder detail	Open child folder/deck, move/create, review folder due	Folders, decks, recursive due summaries	Empty folder: create deck or move items here	Authenticated owner
`/decks/library`, `/decks/public`	Prebuilt library	Add/copy public deck, filter level/language	Public/system decks, CEFR metadata	No matches: reset filters	Authenticated
`/decks/new`	New deck	Name, paste content, choose folder	Deck, language pair	Missing translation service/content errors inline	Authenticated
`/decks/:id`	Deck detail	Start review, choose mode, edit, export Anki, copy public deck, manage cards	Deck, cards, review stats, source links	No cards: add cards/import/generate	Owner or public visibility
`/decks/:id/edit`	Edit deck	Rename, move folder, delete, add cards	Deck, folders, cards	Public copied deck cannot edit original	Owner/admin
~~`/decks/:id/choose`~~	Superseded (#294 launcher pattern): mode is the sticky `review_mode` setting, resolved at session start — no chooser page. If the sticky mode is unavailable for the deck, the session falls back to Read and says so once in the session shell	—	Mode availability by card type	—	—
`/decks/:id/review/:mode`	Review session	Answer/reveal, grade, chat, finish session	Cards, FSRS preview, review session	No due cards: show summary/next due	Authorized deck access
`/decks/reviews/history`	Review history	Filter sessions; “Review N missed” starts a fresh session scoped to that session’s Again/Hard cards, same mode preselected — grades log to FSRS normally, original session rows untouched (#294 launcher pattern)	Review sessions, reviews	No history: link to Decks	Authenticated

Grammar Sitemap

Grammar is a primary tab. It is organized by level and area for browsing, note reading, exercises, and grammar review. The Profile progress map summarizes grammar mastery but does not replace the Grammar workspace.

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/profile/progress`	Cross-domain progress map	Filter domain/level, review due/weak, open recommended action	Grammar masteries, verb/deck/document rollups, review sessions, recommendations	No progress: show onboarding starter path	Authenticated
`/grammar`, `/grammar_notes`	Grammar tab overview	Browse by level/area, search/filter, review due, open note	Grammar notes, categories, bookmarks, mastery summaries	No results: clear filters	Authenticated
`/grammar/categories/:id`, `/grammar_categories/:id`	Category detail	Review category, open notes	Grammar category, notes, mastery rollups	No exercises: read notes and generate practice	Authenticated
`/grammar/levels/:level`	Level detail	Review all due, open categories	Level rollups, categories	No progress: show level starter list	Authenticated
`/grammar/notes/:id`, `/grammar_notes/:id`	Grammar note	Toggle target/fluent, practice, bookmark, chat	Note, translations, exercises, mastery	No translation/exercises: show available note and generation state	Published note, authenticated
`/grammar/review`	Grammar card review	Answer dropdown/blank/multiple choice, grade, chat	Grammar-sourced cards, review session	No due cards: show recommendations	Authenticated
`/grammar/recommendations`	Recommended grammar queue	Start, dismiss, save recommendation	Recommendation service	No recommendations: show browse by level	Authenticated

Verbs Sitemap

Verbs is a primary tab for signed-in users and remains the signed-out public entry. The signed-in version keeps the utility of the public conjugator while adding saved verbs, weak-verb practice, examples, audio, and deck creation.

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/verbs`	Verb tab/search	Search, filter language, open verb, resume weak verbs	Verb lemmas, saved verbs, recent verbs, weak conjugation rollups	No query: show common/recent/recommended verbs	Public with signed-in extras
`/verbs/:id`	Verb detail	Switch tense/mood, listen, save, create deck, start weak-form review	Verb lemma, conjugations, tenses, examples, audio, user ability	Missing examples/audio: show generation state	Public with signed-in extras
`/verbs/:verb_id/conjugations/:id`	Conjugation detail	Listen, view/generate example, add to deck, practice form	Conjugation, sentences, audio, source links	Missing sentence/audio: generate for signed-in users	Public with signed-in extras
`/verbs/saved`	Saved verbs	Review, filter, create deck	Saved verbs/bookmarks, due summaries	Empty: save verbs from search/detail	Authenticated
`/verbs/review`	Verb review	Produce forms, listen/repeat, grade, chat	Verb-sourced cards, template registry, review session	No due verb cards: show deck/recommendation paths	Authenticated
`/verbs/decks/new`	Verb deck builder	Choose verb/tense/mood/level, preview, create deck	Verb lemmas, tenses, conjugations, examples	Too few examples: generate or create without examples	Authenticated

Documents Sitemap

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/documents`	Documents index	Open file/folder, upload, create, search/filter	Documents, folders, import status	No documents: upload, paste, or try sample	Authenticated
`/documents/folders/:id`	Folder detail	Open, move, rename, create/upload	Folder tree, documents	Empty folder: upload/create actions	Owner or granted teacher scope
`/documents/upload`	Import	Upload PDF, image, text file, photo, or mobile scan	ActiveStorage blob, import job	Unsupported file: explain accepted types	Owner
`/documents/new`	Create/paste/write document	Title, prompt card, paste/write, save	Document draft, weak areas, prompt builder	Empty content: save disabled or draft prompt	Owner
`/documents/:id`	Show mode sentence reader	Play sentence, translate, save vocab, read aloud, choose voice, chat	Document sentences, translations, audio, study events, voice preference	Processing: show import/segmentation status	Owner or granted teacher scope
`/documents/:id/words`	Show mode word reader	Tap word, translate/listen, save vocab	Document words, word translations/audio	Whitespace/punctuation ignored	Owner or granted teacher scope
`/documents/:id/dictation`	Dictation	Slow playback, repeat key words, submit typed/photo answer	Sentences, audio, writing submission	No audio: prepare audio first	Owner
`/documents/write`	Writing prompt	Generate prompt, write, submit	Weak areas, recent study, prompt builder	No weak areas: use level-based prompt	Authenticated
`/documents/writing/:id`	Writing feedback	Review corrections, alternatives, grade, chat	Writing submission, correction JSON	Processing: show correction job state	Owner
`/documents/:id/edit`	Edit mode	Rename, edit content/formatting, submit for correction, delete, move	Document, folder, prompt, revisions	Reprocessing state after content changes	Owner
`/documents/:id/revisions`	Edit history	View, compare, restore	Document revisions, snapshots, actor/reason	No history: show current version only	Owner

Profile Sitemap

Profile sub-tab persists per user. /profile should redirect to the last used profile sub-tab, defaulting to /profile/progress.

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/profile/progress`	Cross-domain progress map and next actions	Review weak/due, open domain detail, start recommendation	Grammar masteries, verb/deck/document rollups, review sessions, recommendations	New user: onboarding starter path	User; teacher if granted
`/profile/activity`	Activity graph	Inspect day, filter event type	Study events or activity day cache	No activity: show first-study action	User; teacher if granted
`/profile/evaluate`	Peer evaluation hub	Show QR/barcode, scan code, view grade flows	Peer grades, QR token	Camera unavailable: manual code entry	Authenticated
`/users/:id/grade/new`	Grade another user	Rate skills, comment, submit	Recipient, peer grade rubric	Expired token: request new code	Authenticated with token/permission
`/profile/grades`	Grades received	Review feedback, filter by skill	Peer grades received	No grades: show QR share action	User
`/profile/grades/given`	Grades given	Review past grades	Peer grades given	No given grades: open evaluate	User
`/profile/vocabulary`	Vocabulary list	Filter, mark known, create deck, review	Vocabulary entries, cards, sources	Empty: collect from documents/grammar	User; teacher if granted
`/profile/chat`	Chat history	Resume, search, start general chat	Chats, messages, context snapshots	No chats: start coach chat	User
`/profile/teachers`	Teacher permissions	Grant/revoke scope, choose expiry	User access grants	No grants: invite/add teacher	User
`/profile/edit`, `/users/:id/edit`	Edit profile	Name, avatar, location, languages	User profile	Validation errors inline	User
`/account_settings`	Account details	Name/gender/account details, default document voices, billing placeholder	User account fields, voice preferences	Billing unavailable: show coming soon	User
`/users/edit`	Change password	Update password	Devise	Current password errors inline	User; final submit by user
`/gdpr_exports`	Data export	Request/download export	User data export	Export processing state	User

Chat Surfaces

Surface	Entry	Context	Return Behavior	Access
Review/test chat	Review screen	Card, answer, expected answer, source, user level	Return to same review card	User reviewing authorized card
Grammar chat	Note/exercise	Grammar note, exercise, selected text, language pair	Return to note/exercise	Authenticated
Document coach	Sentence/word reader	Document, selected segment, translation, saved vocab	Return to reader position	Owner or granted teacher scope
Writing coach	Feedback page	Submission, correction, alternatives, CEFR grade	Return to feedback	Owner
General coach	Profile/global action	User language pair, weak areas, recent study	Return to prior page or Profile chat	User

Account and Public Info

Route	Purpose	Primary Actions	Data	Empty/Edge State	Access
`/account_settings`	Account fields	Update account info and default document voices	User, voice preferences	Validation errors inline	User
`/users/edit`	Password credentials	Change password	Devise	Current password required	User
`/users/:id/edit`	Profile fields	Update avatar/languages/location	User, ActiveStorage	Upload too large: show file limit	User
`/faq`, `/about`, `/contact_us`, `/privacy`, `/terms`, `/cookies`	Support/legal	Read, contact	Locale/static content, Contact	Missing locale: English fallback	Public

Permission Summary

Public: verb conjugator, verb details, info/legal, login/signup.
Authenticated user: own Decks, Documents, Profile, Grammar progress, Verbs progress, vocabulary, chats, reviews, writing, grades.
Public deck visibility: public/system decks are readable/copyable by authenticated users; owners/admins can edit.
Teacher/viewer: access only through user_access_grants and only for granted scopes.
Admin/editor: existing admin/editor abilities remain secondary and should not appear as primary learner navigation.
Sensitive actions: deleting files/accounts, submitting password changes, payment/billing, outbound uploads, and third-party messages require explicit user confirmation at action time in agent workflows.

Claude Design Brief

Use this section as the final Claude Design assignment. It is written to be pasted into Claude Design with the codebase, this document, and the screenshot pack attached.

Claude Design Workflow Fit

Verified against Anthropic’s official Claude Design announcement on 2026-04-28: Claude Design accepts text prompts, uploaded images/documents, codebase context, and website captures; it supports iterative refinements such as inline comments and direct edits; and it can export or hand off a finished design bundle to Claude Code. Source: https://www.anthropic.com/news/claude-design-anthropic-labs

The end-to-end loop between GitHub issues, Claude Code, and Claude Design — including which steps are automated and which require the claude.ai UI — is specified in docs/technical/design_system_workflow.md.

Recommended workflow:

Start a project at https://claude.ai/design.
Create a new Claude Design system named Immersive Design System.
Attach this design document.
Attach the screenshot folder docs/features/immersive_redesign_screenshots/.
Attach docs/technical/turbonative/ and lib/tmp-bridge-components/bridge-components/ as implementation reference material.
Give Claude Design access to the codebase or at least app/assets/stylesheets/, app/views/, app/javascript/controllers/, config/routes/, and this document.
Use web capture against the local app for the key existing pages if available.
First ask Claude Design to build the new design system from the existing Rails/CSS app, screenshots, and this brief.
Then create the high-fidelity desktop and mobile prototype for the full P0+P1 product scope using that design system.
Ask Claude Design for a Claude Code handoff bundle.

Source Inputs

Primary brief:

immersive_redesign_extension_design.md

Code/design context:

app/assets/stylesheets/: existing custom CSS, tokens, list rows, responsive patterns.
app/views/: Rails ERB structure and current page/component conventions.
app/javascript/controllers/: Stimulus interaction patterns.
config/routes/: current route names and compatibility constraints.
app/models/, app/controllers/, app/services/: technical surface for implementation realism.
docs/technical/turbonative/: Hotwire Native/Turbo Native guidance for Rails, iOS, Android, path configuration, native tabs, bridge components, and native-vs-web decisions.
lib/tmp-bridge-components/bridge-components/: local reference copy of bridge-component source. Use it as adaptation material, not as an app dependency.
/Users/sean/src/37signals/writebook/: reference implementation for markdown-backed Rails writing, custom rendering, autosave, and edit history patterns. Use as inspiration only; do not copy product identity or unrelated book-publishing flows.

Existing screenshot references:

File	Current Surface
existing deck index screenshot	Decks index list rows.
existing deck filters screenshot	Decks index with filter/search bar open.
existing-03-auth-profile-menu-open-vp.jpg	Current top-right authenticated dropdown, which may be replaced.
existing deck detail screenshot	Deck detail/card list.
existing-05-review-read-mode-vp.jpg	Review session, read mode.
existing-06-review-write-mode-vp.jpg	Review session, write mode.
existing-07-documents-index-vp.jpg	Documents index list rows.
existing-08-document-reader-sentences-vp.jpg	Document reader sentence view.
existing-09-document-reader-words-vp.jpg	Document reader word-token view.
existing-10-grammar-index-vp.jpg	Grammar note index list rows.
existing-11-grammar-note-english-vp.jpg	Grammar note in fluent-language explanation view.
existing-12-verbs-index-authenticated-vp.jpg	Verb index while authenticated.
existing-13-verb-detail-vp.jpg	Verb detail/conjugation table.
existing-14-conjugation-detail-vp.jpg	Conjugation detail with example sentence.
existing-15-profile-current-vp.jpg	Current sparse `/profile` page.
existing-16-account-settings-vp.jpg	Account settings form.
existing-17-onboarding-language-current-vp.jpg	Current pre-signup language selection.
existing-18-profile-edit-vp.jpg	Current edit profile page at `/users/:id/edit`.
existing-19-change-password-vp.jpg	Current Devise change password page at `/users/edit`.
existing-20-info-faq-vp.jpg	Public FAQ page.
existing-21-info-contact-vp.jpg	Public contact page/form at `/contact_us`.
existing-22-info-about-vp.jpg	Public about page.
existing-23-info-privacy-vp.jpg	Public privacy page.
existing-24-info-terms-vp.jpg	Public terms page.
existing-25-info-cookies-vp.jpg	Public cookie consent page.

Reference screenshot examples:

File	Design Lesson
example-1-anki-decks.png	Anki-style nested deck hierarchy with compact New/Learn/Due count columns and fast review orientation. Use the information architecture, not the literal visual style.
example-2-kwiziq-quizes.png	Mixed grammar quiz formats in one sequence: dropdown, typed blank, hints, translation context, and multiple choice. Use this to shape grammar card templates.
example-3-anki-card-1.png	Verb/conjugation explanation card with table, example sentence, and FSRS grade strip.
example-4-anki-card-2.png	Phrase translation reveal card with large prompt/answer hierarchy and minimal chrome.
example-5-anki-card-3.png	Sentence translation card with audio action and source grammar tag.
example-6-anki-card-4.png	Verb form/listening card with multiple audio affordances and target/fluent-language support.
example-7-anki-card-5.png	Verb production card keyed by lemma, pronoun, tense, and answer forms.
example-8-anki-card-6.png	Sentence transformation/cloze card with compact prompt-to-answer reveal.
example-9-grammarly-chat-open.png	Writing/document correction with inline marks, suggestion popover, side AI chat, score panel, stats, and fixed writing toolbar.
example-10-grammarly-chat-closed.png	Writing/document workspace with a collapsed right-side tool rail and bottom chat input.

Suggested web-capture targets:

/
/decks
/documents
/grammar
/profile
/account_settings
/users/:id/edit
/users/edit
/user_informations/new
/faq
/contact_us

Bridge-Component Source Guidance

Use lib/tmp-bridge-components/bridge-components as local source material for Immersive-owned bridge components. Do not add @joemasilotti/bridge-components, the Swift package, or the Android/JitPack dependency directly. Absorb the patterns and selected code into Immersive-owned namespaces so the app can evolve the contracts safely.

Build structure:

Keep the mobile apps in this repository as top-level folders: ios/Immersive/ and android/Immersive/.
Copy/adapt selected web controllers into app/javascript/controllers/bridge/.
Copy/adapt selected iOS components into ios/Immersive/App/Components/ and shared helpers into ios/Immersive/App/Bridge/.
Copy/adapt selected Android components into android/Immersive/app/src/main/java/com/immersiveapp/immersive/bridge/.
Rename package/module names away from com.masilotti.bridgecomponents and Bridgework where needed; use Immersive-owned names such as ImmersiveBridge.
Preserve the bridge contract: Rails markup uses data-controller="bridge--name", Stimulus extends BridgeComponent, native component names match the web component name, and CSS hides web controls only when [data-bridge-components] advertises support.
Keep web fallback controls visible for normal browsers and older app builds.
Register only the components Immersive actually uses, then expand intentionally.
For document scanning, improve the copied demo contract before production use. The reference web controller expects one base64 JPEG, but Immersive should support multiple scanned pages and should prefer native-uploaded file references or signed blob IDs over large base64 payloads through the web view.

Bridge components in scope:

Component	Immersive Use
`form`	Native submit buttons for onboarding, account, profile, deck, and document forms.
`button`	Native toolbar buttons for Save, Add, Done, Edit, and contextual actions.
`share`	Share deck/document links through native share sheets.
`toast`	Confirm saved vocabulary, copied deck, submitted grade, and completed review.
`haptic`	Subtle feedback for review grades and successful saves in the native apps.
`search`	Native search affordance for Decks, Documents, Vocabulary, and Chat history.
`menu`	Native overflow/action menus for deck, document, and profile actions.
`barcode-scanner`	Scan another user’s evaluation QR/barcode. The local source includes iOS scanner code; Android needs an Immersive-owned ML Kit/Play Services implementation following the copied docs.
`document-scanner`	Scan paper documents or photos into the document import/OCR flow. The local source includes iOS scanner code; Android needs an Immersive-owned ML Kit document scanner implementation following the copied docs. Extend the contract for multiple pages and blob/file references rather than one base64 image.

Paste-In Prompt

Design a redesign and extension of Immersive, a Rails language-learning app for spaced repetition, grammar, verbs, documents, writing, chat, and progress tracking.

Use the attached main design document as the source of truth. This prompt is a scoped assignment for the full P0+P1 design scope, not a separate strategy document. Use the existing screenshots as current-state references and the example screenshots as product-pattern references, not as literal target visuals. The product direction is a serious language-learning companion for people also learning through classes, books, tutors, conversation, and self-study. It should feel warm, useful, progress-oriented, dense enough for daily study, and closer to 37signals than a game. The confirmed visual register is the one established by the shipped bridge contrastive components (equivalence table, grammar callout, sentence decomposition, annotated line-numbered reading): subtle, intellectual, academic — a well-set textbook's scholarly apparatus, achieved with hairline rules, muted ink, typography and spacing doing the structural work, and a single accent color used sparingly to mark the target language. Aim new designs at that register. Its core premise, per "Product North Star" in the attached document, is cross-linguistic transfer: a learner who already knows one or more of the six Bridge languages (English, Spanish, French, Italian, Portuguese, Catalan) should be able to acquire another one faster through explicit comparison, informed by the EuRom5 intercomprehension method (see the attached document for the specific diagram patterns: cross-language equivalence tables, grammar comparison callouts, sentence decomposition diagrams, annotated line-numbered reading — plus the inline reader aid classes: inference nudge with progressive disclosure before translation, skip markers, listen hints, morphology decomposition, title orientation, grammar cross-refs). Design these as first-class, visible UI patterns in Grammar and Documents, not as a marketing narrative layered on top of an otherwise language-agnostic product. The reader's success state is global comprehension with a right to approximation — never word-by-word translation completionism.

Work in two Claude Design workflow steps, but keep this as one product scope. Step 1: create a new `Immersive Design System` from the existing Rails/CSS app, screenshots, and this brief. Review the existing Rails/CSS system from `app/assets/stylesheets/`, `app/views/`, and `app/javascript/controllers/`. Preserve the custom CSS approach and extend it with a small, coherent component system. Produce design-system guidance first: tokens, app shell, list rows, toolbars, segmented controls, progress states, review cards, document tokens, chat drawer/sheet, forms, settings surfaces, empty/loading/error/success states, and dark-mode behavior. Step 2: create the high-fidelity desktop and mobile product design for the full P0+P1 scope using that design system. Do not treat P0 and P1 as separate design phases.

Hard constraints:
- Do not create a generic marketing landing page. The signed-out root remains a useful verb conjugator.
- Do not add Bootstrap, Tailwind, React, Vue, or a framework-like visual reset.
- Use system fonts and existing semantic OKLCh tokens; propose only minimal token additions.
- Build on the existing custom CSS and Rails ERB patterns first. Do not redesign as if this were a new app.
- Authenticated primary navigation has exactly five tabs: Decks, Documents, Profile, Grammar, Verbs.
- Grammar and Verbs are first-class primary tabs. The Profile progress map summarizes them but does not replace those workspaces.
- Use Deck and Decks everywhere in user-facing product language. Do not use the previous product label.
- Design all P0+P1 scope together as one coherent release. Do not split the design into separate P0 and P1 phases.
- Design review screens as template-driven cards. Do not assume each new test format requires a new database subclass.
- Treat document markdown/basic formatting as an authoring layer only. The reading surface must preserve sentence/word interaction through an Immersive-owned reader renderer plus Stimulus behavior.
- In document views, support Show mode for reading and Edit mode for writing/editing.
- "Read to me" voice selection happens in the document view and is saved as a user default that is also manageable from Profile/account settings.
- Replace the current top-right authenticated dropdown as primary navigation. Account/chat/logout can remain compact secondary actions.
- Use list rows for indexes, not card grids.
- Avoid nested cards, decorative blobs, oversized marketing sections, and one-note blue/purple/slate palettes.
- All visible text must be localizable.
- Treat iOS and Android as top-level folders in this repo: `ios/Immersive/` and `android/Immersive/`.
- Treat `lib/tmp-bridge-components/bridge-components` as reference code to absorb into Immersive-owned bridge components, not as a direct dependency.
- Design the EuRom5-informed contrastive patterns (equivalence table, grammar callout, sentence decomposition, annotated line-numbered reading) as comparisons against whichever Bridge language(s) the learner actually knows, not a fixed single "fluent language" — the current single-column data model is a known gap being addressed separately, not a design constraint to design around.
- Do not treat EuRom5 itself as a template to copy wholesale: it is comprehension-only (reading/listening), with no spaced repetition and no production practice. Immersive keeps FSRS review and writing/speaking practice; only the comparison/annotation patterns are adapted from it.

Design desktop 1280px and mobile 375px versions. Include light mode for all required screens and dark mode for the most important screens.

Required screens:
1. Public verb conjugator root.
2. Public verb detail/conjugation detail pattern.
3. Onboarding language selection with six languages: English, Spanish, French, Italian, Portuguese, Catalan.
4. Onboarding level step and optional subscription prompt.
5. Authenticated shell with Decks, Documents, Profile, Grammar, and Verbs tabs.
6. Decks index with folders, due/new/learning counts, search/filter, create, and library actions.
7. Deck detail and mode chooser.
8. Deck review session with read/write/listen/speak mode treatment, Again/Hard/Good/Easy buttons, and contextual chat.
9. Grammar tab overview by level and area.
10. Grammar note with target/fluent toggle, explanation, exercises, and chat.
11. Grammar review card/session.
12. Verbs tab/search, verb detail, conjugation detail, and deck creation path.
13. Documents index with folders/files/upload/create/scan actions.
14. Document show mode with sentence and word modes, translation, audio, save vocabulary, "Read to me", voice picker, and document coach.
15. Document edit mode with prompt card, basic formatting, correction feedback, alternatives, and edit history.
16. Dictation and writing correction flow.
17. Profile progress map with grammar, verbs, decks, documents, vocabulary, writing, ratings, efforts, due/weak states, and recommendations.
18. Profile activity graph.
19. Profile evaluate/QR grading flow.
20. Profile vocabulary list.
21. Chat panel, mobile bottom-sheet chat, and chat history.
22. Public info article/form shell for FAQ, contact, about, privacy, terms, and cookies.
23. Account/profile settings patterns for edit profile, default document voice, account settings, and change password.

Design expected states:
- Empty states for new users, empty folders, no decks, no documents, no vocabulary, no chat history, and no public deck matches.
- Loading/processing states for document import, OCR, audio generation, writing correction, and AI example generation.
- Error states for validation, unsupported uploads, missing translations, no verb results, expired QR code, and unavailable billing.
- Success states for saved profile, copied deck, completed review session, saved vocabulary, and submitted peer grade.

Produce:
- An interactive prototype or screen collection.
- Desktop and mobile versions.
- Dark mode variants for public verb conjugator, authenticated shell, Decks index, review session, Grammar tab, Verbs tab, document show/edit modes, and Profile.
- Component inventory and token additions.
- Notes on responsive behavior, Hotwire Native/Turbo Native behavior, native tab behavior, and bridge-component opportunities.
- A concise handoff bundle for Claude Code with implementation notes, prioritized screens, component names, and CSS/token guidance.

Required Design Outputs

Design all P0+P1 screens as one coherent release scope:

Design system foundation: tokens, app shell, navigation, list rows, local toolbars, segmented controls, progress states, review controls, document tokens, chat drawer/sheet, forms, settings, states, and dark mode rules.
Public verb conjugator root.
Public verb detail/conjugation detail pattern.
Onboarding language selection with six languages: English, Spanish, French, Italian, Portuguese, Catalan.
Onboarding level step and optional subscription prompt.
Authenticated shell with Decks, Documents, Profile, Grammar, and Verbs tabs.
Decks index with folders, due/new/learning counts, search/filter, create, and library actions.
Deck detail, mode chooser, and review session.
Grammar tab overview by level and area.
Grammar note with target/fluent toggle, explanation, exercises, and chat.
Grammar review card/session.
Verbs tab/search, verb detail, conjugation detail, and deck creation path.
Documents index with folders/files/upload/create/scan actions.
Document show mode with sentence and word modes, translation, audio, save vocabulary, “Read to me”, voice picker, and document coach.
Document edit mode with prompt card, basic formatting, correction feedback, alternatives, and edit history.
Dictation and writing correction flow.
Profile progress map with grammar, verbs, decks, documents, vocabulary, writing, ratings, efforts, due/weak states, and recommendations.
Profile activity graph.
Profile evaluate/QR grading flow.
Profile vocabulary list.
Chat panel, mobile bottom-sheet chat, and chat history.
Public info article/form shell for FAQ, contact, about, privacy, terms, and cookies.
Account/profile settings patterns for edit profile, default document voice, account settings, and change password.

Component Inventory

Design or refine these reusable components:

app-shell: desktop top tabs and mobile bottom tabs.
secondary-nav: Profile sub-tabs and local mode controls.
list-row: folder, deck, document, grammar note, vocabulary, review history variants.
count-badge: due, new, learning, review, weak, mastered.
progress-meter: bar/ring/dot variants for CEFR and mastery.
activity-heatmap: GitHub-style profile activity.
review-card: prompt, reveal/input, answer feedback, grade buttons.
card-template: reusable prompt/answer shells for grammar dropdown, cloze, verb production, sentence translation, dictation, and writing-correction cards.
segmented-control: modes and target/fluent toggles.
document-token: sentence/word selectable text with translation/audio states.
document-reader: formatted show-mode reader using server-rendered sentence/word-aware spans.
document-voice-picker: choose read-aloud voice/rate and save language default.
document-revision-list: edit/import/correction history with compare and restore actions.
writing-prompt-card: optional prompt, focus areas, target length, and regenerate/difficulty controls.
writing-alternative: natural/simpler/formal/casual alternatives with replace/insert/explain/create-card actions.
chat-drawer: contextual chat trigger, panel, history row.
mobile-chat-sheet: bottom-sheet chat with selected context and full-screen expansion.
empty-state: compact, action-led, not illustrative-heavy.
qr-evaluation-card: show code, scan/manual entry, grade summary.
upload-dropzone: document imports and photo upload.
settings-form: profile, account, password, billing placeholder.
bridge-equivalence-table: word/phrase comparison across the learner’s known Bridge language(s) and the target, line- or term-referenced (EuRom5-informed, see Product North Star).
bridge-grammar-callout: inline comparison box for one grammatical construction across multiple Bridge languages (EuRom5-informed).
sentence-decomposition-diagram: lightweight S/V/O breakdown for parsing a hard sentence (EuRom5-informed).
reader-aid-mark: the inline aid classes on reader tokens/spans — inference nudge (phantom word), skip marker, listen hint, morphology decomposition, already-seen pointer, grammar cross-ref (EuRom5-informed; see the aid taxonomy in bridge_method.md). Visual language: subtle marks in the margin/underline register of the shipped bridge components, never highlighter noise.

Token and Style Guidance

Keep the existing semantic token approach.
Add tokens only for progress, review feedback, heatmap intensity, and subtle navigation states.
Keep border radius at 8px or less unless an existing component already differs.
Use system fonts and no font downloads.
Keep letter spacing at normal.
Avoid viewport-scaled font sizes.
Keep UI dense but readable.
Use icons for clear commands, especially review controls, upload, search/filter, folder actions, chat, audio, save vocabulary, and settings.
Every icon-only action needs a tooltip or accessible label.

Interaction Guidance

Decks/Documents/Profile/Grammar/Verbs are always visible as primary navigation when authenticated.
Review and dictation flows should reduce surrounding chrome and keep focus on the task.
Grammar and Verbs tabs should support study directly, while the Profile progress map should route to the right note, verb, deck, document, or review session in one click.
Document show mode should let users move fluidly between sentence mode, word mode, translation, audio, read-aloud, save-vocab, voice choice, and chat.
Document edit mode should keep writing primary while making prompts, corrections, alternatives, and revision history available without turning the editor into a cluttered dashboard.
Chat should feel contextually available, not constantly visually loud.
On mobile, contextual chat uses a bottom sheet instead of a desktop-style side panel.
Profile should feel like the learner command center: progress map first, then activity, evaluate, grades, vocabulary, chat, teachers, permissions, account.
Public info pages should share a quiet article/form shell and never compete with the verb conjugator as the public entry.

Claude Code Handoff Requirements

The handoff bundle should include:

Prioritized screen list.
Component list with proposed class names or component names.
Token additions with names and intended use.
Notes on which existing screenshots informed each new screen.
Desktop/mobile behavior notes.
Dark mode notes.
Accessibility notes for keyboard focus, form errors, review buttons, QR scanning fallback, document tokens, and chat.
Implementation notes aligned with Rails ERB, Turbo, Stimulus, custom CSS, localization, and the template-driven card architecture.
Explicit warnings not to preserve the current top-right dropdown as primary navigation and not to build a new marketing landing page.

Review Checklist

Before accepting the Claude Design output:

The signed-out first screen is still the verb conjugator.
Authenticated primary navigation has Decks, Documents, Profile, Grammar, and Verbs.
Index surfaces are list rows, not card grids.
The profile page is a command center, not a sparse profile card.
Grammar and Verbs are first-class tabs, and their progress is visible from Profile.
Documents include folders, reader, dictation, writing, translation, audio, vocabulary, and chat paths.
Document design separates Show mode from Edit mode.
Document formatting does not break sentence/word click behavior.
Document voice choice is available from the reader and manageable from Profile/account settings.
Mobile chat is represented as a bottom sheet, not a squeezed desktop side panel.
Review sessions have clear grade controls and contextual chat.
Public FAQ/contact/about/legal pages have a reusable support article/form shell.
Mobile and desktop information architecture match.
Dark mode is not just inverted colors.
The handoff is specific enough for Claude Code to implement in the existing Rails/CSS system.
At least Grammar and Documents show a working example of the EuRom5-informed contrastive patterns (equivalence table, grammar callout, sentence decomposition), not just a mention in the writeup.
The contrastive patterns compare against the learner’s known Bridge language(s), not a hardcoded single language.

Document Strategy

Keep this as one canonical main design document for Claude Design. Do not split the design brief into separate phase files for the P0+P1 design pass. The Claude Design assignment should treat the whole P0+P1 scope as one coherent product and design system.

Market Need Review

Market Context

The Immersive redesign sits between six existing learner behaviors:

Learners use Anki when they want powerful, customizable memory work. Anki’s public positioning is clear: spend more time on challenging material and less on what is already known, with decks, reviews, media support, sync, customization, add-ons, and large collections.
Learners use Readlang or LingQ when they want to learn from real texts and listening material. Readlang’s promise is especially close to Immersive Documents: click to translate, practice translated words with flashcards, upload texts, use context-aware explanations, and export vocabulary to Anki. LingQ validates the broader input-learning category: import books/articles/video/podcast content, read/listen, save vocabulary, track progress, and use AI tools.
Learners use Kwiziq when they want grammar diagnosis and an evolving personal plan. Its Brainmap/progress-plan positioning is close to Immersive’s Grammar/Profile ambition.
Learners use DeepL Write or Grammarly/Superhuman when they want correction, tone, alternatives, and rewriting. These tools validate writing assistance, but they do not turn mistakes into a learner’s long-term grammar/vocabulary plan.
Learners use Duolingo when they want a guided, gamified, bite-sized course. This is not Immersive’s target experience, but it sets expectations for low-friction daily engagement.
Learners use teachers, tutors, books, and classes for accountable progress. Immersive should be a companion to those sources, not a replacement course.

Core Market Bet

Immersive should not try to beat Anki at generic flashcards, Readlang/LingQ at pure reading volume, Kwiziq at grammar-only diagnosis, or Grammarly/DeepL at general-purpose writing polish. The market opening is the connected loop:

Start with a practical public utility: verb lookup and conjugation.
Let learners import or write real target-language material.
Let them tap, translate, listen, correct, and ask for help in context.
Convert meaningful moments into FSRS-backed cards.
Show progress by grammar, verbs, documents, vocabulary, writing, and activity.
Support a teacher/tutor/class relationship through scoped visibility and grades.

The product is strongest when the user thinks: “I am already studying elsewhere, and Immersive turns that study into memory, feedback, and progress.”

Wedge Assessment

Wedge	Market Signal	Immersive Fit	Risk	Recommendation
Public verb conjugator	Search-driven utility; app already has strong verb data.	Excellent acquisition wedge and trust builder.	Utility may not convert without obvious save/review actions.	Keep signed-out root as verb conjugator; add clear signed-in actions around save, examples, audio, and deck creation.
Documents reader/writer	Readlang and LingQ validate imported-content learning and paid reading features.	Strongest paid wedge if connected to decks, writing, chat, and vocabulary.	A basic reader will look like a weaker Readlang.	Make Documents the first monetizable workspace: import/scan, click-to-translate, listen, save vocab, read aloud, writing correction, cards.
Grammar progress	Kwiziq validates grammar diagnosis, weak-area plans, and progress maps.	Strong differentiator when tied to FSRS cards and writing/doc mistakes.	Requires high-quality exercises and reliable mastery signals.	Ship grammar browse/progress early, but keep full diagnosis/generation behind a staged rollout.
Decks/FSRS	Anki validates memory, but dominates generic card workflows.	Retention engine and evidence layer for every other feature.	Weak as standalone acquisition.	Do not market as “Anki replacement”; position as review automatically fed by Immersive work, with Anki export for user decks.
Writing correction	DeepL Write and Grammarly validate alternatives, tone, and correction UX.	High-value companion feature when mistakes create learning cards.	General writing tools are very strong.	Focus on target-language learning feedback, CEFR level, grammar/vocab links, alternatives, and mistake-to-card conversion.
Profile progress	Kwiziq/LingQ/Duolingo validate progress visibility.	Strong as command center once data exists.	Empty dashboard problem for new users.	Keep Profile as landing/summary, but route users quickly to Documents, Grammar, Verbs, or Decks actions.
Teacher/peer grades	Tutors/classes are a real learning context.	Differentiates from solo apps.	Could be too niche or socially awkward if overbuilt.	Keep QR grading and teacher visibility scoped and simple until classroom/tutor demand is proven.

P0+P1 Big-Bang Scope Recommendation

The first market-testable design should cover all P0+P1 scope as one coherent release. Implementation can still be sequenced internally, but Claude Design should see the complete target system.

Public verb conjugator with signed-in save/add-to-deck paths.
Authenticated shell with five tabs, but with Documents and Decks receiving the deepest implementation.
Documents show mode: upload/paste text, sentence/word click, translation, audio, save vocabulary, read-aloud voice preference, contextual chat entry.
Documents edit mode: write/paste, prompt card, correction, alternatives, edit history, create cards from mistakes.
Deck review: FSRS-backed review session, source-linked cards, Anki export for user decks.
Grammar: level/area navigation, notes, exercises, grammar cards, grammar review, progress, and recommendations.
Verbs: signed-in workspace, saved/weak verbs, examples/audio, deck creation, and review paths.
Profile progress: activity, due cards, vocabulary collected, document work, grammar/verb progress, teacher permissions, peer grades, account/settings, and chat history.
Mobile/native: five tabs, scanner flows, native bridge affordances, mobile chat sheet, and web fallbacks.

Riskiest Assumptions

Learners who already use Anki/Readlang/LingQ/Kwiziq will value one connected workflow enough to switch or add another paid tool.
The document reader/writer can be good enough to compete with specialized reading and writing tools.
Grammar progress can be credible without a large hand-authored exercise bank at launch.
The public verb conjugator can generate signups at meaningful volume.
Writing correction can feel pedagogical rather than generic AI rewriting.
Teacher/peer grading is a real buying trigger rather than a nice-to-have.

Validation Questions

“Which wedge is most compelling for acquisition” is answered in docs/features/immersive_business_plan.md’s “Core Strategic Reframe” - Documents (the demoable click-to-translate/listen/save loop) and the teacher/classroom channel, not the public verb conjugator, which stays a free SEO/trust asset rather than the conversion engine. That business-plan doc also set the $9.99/mo-or-$89/yr price anchor (as a starting point, not a validated price) and the Phase 0 -> Phase 1 decision-gate thresholds (D7 retention >= 20%, 3+ unprompted “I’d pay for this” signals). The remaining questions below are still open, pending real Phase 0 usage data:

When a learner imports a real document, do they naturally save words/sentences and return to review them?
Is “mistakes become cards” compelling enough to differentiate writing correction from Grammarly/DeepL?
Do learners care more about grammar progress maps or immediate document/writing help?
Does Anki export increase trust, or does it encourage users to leave Immersive after generating decks?
Which user segment responds most strongly: classroom learners, tutor-supported learners, self-study readers, or verb/grammar search users?
Is the unified loop stronger than using Anki, a conjugator, a grammar site, a translator, and a writing checker separately, enough that a learner already using those tools switches or adds Immersive alongside them?
Does the Decks/Documents/Profile/Grammar/Verbs navigation match how serious learners think about daily study?
Is grammar progress valuable enough to differentiate Immersive from static grammar references and quiz sites?
Is document-based learning a strong enough paid feature, especially with dictation, writing correction, and vocabulary capture?
Should peer “grades” be private peer feedback, formal teacher assessments, or both?
Should teacher permissions expose all progress or only scoped lists and charts?
Should vocabulary be a first-class deck, a generated system deck, or a filtered source list with optional deck creation?
Should prebuilt decks be copied into a user’s account or subscribed to in place?

Immersive Redesign and Extension Design

Executive Summary

Product Direction

Current-State Codebase Summary

Application Shape

Existing Learning Foundation

Decks

Grammar

Documents

Verbs

Users, Profile, Onboarding, and Permissions

Chat and AI

Design System and UI Code

Testing and Implementation Risk

Existing UI and Browser Flow

Public Root and Login

Public Info Pages

Authenticated Navigation

Onboarding

Decks

Review Sessions

Grammar

Documents

Verbs

Profile and Account

Existing UI Implications

Product North Star

EuRom5-Informed Contrastive Patterns

Feature Design

Decks

Grammar

Documents

Verbs

Profile

Chat

Onboarding

UX Design

Navigation Direction

Signed Out

First Account Flow

Authenticated Primary Tabs

Design System Direction

Technical System Design

Architecture Decisions

Core Data Model

Review and FSRS Pipeline

Decks

Grammar

Documents and Writing

Verbs

Profile, Evaluation, and Permissions

Chat Everywhere

Onboarding and Subscription

Services and Jobs

Big-Bang P0+P1 Build Scope

Page Flow and Sitemap

Route Strategy

Global Page Flow

Navigation Model

Public Sitemap

Onboarding Sitemap

Authenticated Shell

Decks Sitemap

Grammar Sitemap

Verbs Sitemap

Documents Sitemap

Profile Sitemap

Chat Surfaces

Account and Public Info

Permission Summary

Claude Design Brief

Claude Design Workflow Fit

Source Inputs

Bridge-Component Source Guidance

Paste-In Prompt

Required Design Outputs

Component Inventory

Token and Style Guidance

Interaction Guidance

Claude Code Handoff Requirements