DOL English Page Role Contracts

DOL English - Page Role Contracts (UX Design)

Purpose

• Giữ ranh giới vai trò giữa các trang learner-facing của DOL English rõ ràng và dễ bảo trì.
• Cho team viết doc, designer, và AI một contract ngắn để tránh trùng vai giữa Home, Program Landing, Exercise Bank, LM, CM, và Vocabulary.
• Giảm việc lặp lại analytics/reward/community ở sai lớp.
• Tách rõ page role khỏi motivation by user phase; phần phase logic xem thêm ENG_Lifecycle_Motivation_Contracts.md.

Reading Rule

• Nếu chỉ cần hiểu navigation như 1 feature hoàn chỉnh, mở ENG_Navigation_00_Overview.md trước.
• File này chỉ giữ page boundary / owner role; không phải one-stop file cho toàn bộ navigation logic.

Core Rule

• Mỗi page chỉ được sở hữu 1 câu hỏi quyết định chính.
• Các block còn lại chỉ được làm một trong 3 việc:
  • đưa bằng chứng ngắn để user tin vào câu trả lời,
  • chuyển câu trả lời đó thành CTA/hành động cụ thể,
  • hoặc deeplink sang owner page khác.
• Nếu 2 page cùng trả lời một câu hỏi, phải chốt:
  • 1 owner page,
  • page còn lại chỉ được giữ ở mức summary, teaser, hoặc browse escape hatch.
• Nếu cùng một hook xuất hiện ở nhiều page, phải chốt:
  • owner hook,
  • owner detail,
  • owner CTA.

Shell Layer Rule

• Logged-in shell của DOL English được đọc theo Program Workspace -> Deep Object, với cross-program aggregate views chỉ là scoped exception ở một vài view đủ điều kiện.
• Không có Global Today hay All Programs workspace như default owner surface sau login.
• Program Workspace luôn chỉ giữ 1 program thật tại một thời điểm.
• Nếu object được surfacing ở aggregate view hoặc page summary khác, completion/progress state vẫn phải đọc từ canonical owner section.

Destination Boundary Rule

• Hôm nay
  • owner question: Bây giờ tôi nên làm gì?
  • giữ orchestration, shortcut, due queue, next action.
• Tiến độ
  • owner question: Tôi đang tiến triển thế nào theo thời gian và yếu ở đâu?
  • giữ analytics, history, weak areas, trend, goal comparison.
• Nếu một surface vừa muốn trả lời next action vừa muốn giữ analytics/history sâu, phải tách rõ owner hoặc merge; không để 2 destination mờ nghĩa cùng sống.

Owner Contracts

• Home
  • Main question: Tôi nên bắt đầu từ chương trình hoặc flow nào?
  • Shell role: Public Discovery Home; không còn là logged-in cross-program execution hub.
  • Allowed evidence: global overview, program chooser, entry points, trust/proof nhẹ, auth/discovery fallback.
  • Not here: post-login orchestration, due queue, analytics sâu, reward wallet/store, pseudo-program workspace.
• Program Landing
  • Main question: Trong chương trình này, tôi đang ở đâu so với mục tiêu và nên ưu tiên module/lane nào tiếp theo?
  • Allowed evidence: goal context, current vs target, countdown, weak skill / weak module cue, module map, weekly strategy, today action translation, browse escape hatch.
  • Not here: Home-style retention orchestration, LM dashboard, leaderboard breakdown dài, reward center.
• Exercise Bank
  • Main question: Nếu tôi muốn tự chọn, tôi sẽ làm bài nào trong kho này?
  • Allowed evidence: bank identity, light stats context, filters, search/sort, list/grid, card CTA states.
  • Not here: diagnosis sâu, recommendation narrative dài, challenge center, reward/archive.
• Learning Management
  • Main question: Tôi học có đều không, yếu ở đâu, tuần này thiếu gì?
  • Allowed evidence: weekly goal state, consistency/heatmap, unfinished and review queues, target gap, mistake clusters, saved/history, next-best translation.
  • Not here: program marketing, reward/archive, social feed.
• Course Management
  • Main question: Tôi đang theo khóa nào, unit nào, deadline và feedback gì?
  • Allowed evidence: worklist, next class, recent result, recap, calendar, light pulse strip.
  • Not here: full achievements archive, deep self-study analytics.
• Vocabulary Dashboard
  • Main question: Hôm nay tôi cần ôn từ nào, và đã nhớ tới đâu?
  • Allowed evidence: today focus, daily progress, review due, memory health, mistake-driven review, lists, heatmap, streak phụ.
  • Not here: full community center, broad practice analytics.

Cross-layer Owner Map

• Today plan -> Program Workspace root / Hôm nay
• Continue unfinished -> Program Workspace root / Hôm nay điều phối, page nguồn sở hữu detail context
• Review đến lịch -> Program Workspace root / Hôm nay điều phối; LM và Vocabulary sở hữu detail/debt view
• Weekly goal -> Program Workspace root / Hôm nay summary; LM sở hữu trạng thái chi tiết
• Target countdown -> Program Workspace root / Hôm nay summary; Program Landing và LM sở hữu reasoning chi tiết
• Current vs target -> Program Landing và LM
• Weak skill / target gap diagnosis -> Program Landing summary, LM detail
• Browse by bank -> Exercise Bank
• Course deadline / feedback -> Course Management
• Vocab due queue / memory health -> Vocabulary Dashboard

Supporting Surface Patterns

• Action surface
  • Mục đích: biến câu trả lời của page thành một hành động bắt đầu ngay.
  • Ví dụ: Continue, Today / This-week Strategy Translation, Fix cũ / Làm mới, Ôn ngay (5 phút).
  • Không được cướp vai câu hỏi chính của page.
• Summary block
  • Mẫu ngắn gọn chuẩn: 1 action signal + 1 progress signal + 1 risk/opportunity signal + 1 CTA.
• Community / recognition teaser
  • Chỉ là động lực nhẹ.
  • Không được biến page thành leaderboard board, badge archive, hay reward center.
• Browse escape hatch
  • Luôn cho user quyền tự chọn nếu page không phải bank.
  • Nhưng browse chỉ là đường thoát có chủ đích, không phải câu hỏi chính của page đó.

Writing Contract

• Mỗi doc page-level nên chốt rõ 5 dòng:
  • Main question
  • Primary decision
  • Allowed evidence
  • Not here
  • Deep links out
• Nếu hook nào đổi trọng số theo user phase, doc phải dẫn chiếu sang contract lifecycle thay vì hard-code trọng số đó như một chân lý cố định.
• First view phải có 1 quyết định nổi trội, không phải nhiều quyết định ngang vai.
• Nếu một block không giúp trả lời câu hỏi chính hoặc không giúp đi tiếp rõ hơn, block đó nên bị cắt, gộp, hoặc đẩy sang owner page khác.

AI-safe Checklist

• Page này đang sở hữu câu hỏi chính nào?
• Có block nào đang trả lời câu hỏi của page khác không?
• Action surface đang là translation hay đang cướp vai page?
• Community/recognition đang là proof nhẹ hay đã thành trọng tâm?
• User có một đường deeplink rõ tới owner page thật sự khi cần xem sâu không?

References

• ./ENG_Navigation_00_Overview.md
• ./ENG_Navigation_Shell_Contracts.md
• ./ENG_Lifecycle_Motivation_Contracts.md

Change log

• 2026-03-27: Bỏ Home post-login = Global Today khỏi active page-role canon; Home quay về public discovery owner, còn Today plan / continue / weekly goal được neo về Program Workspace root / Hôm nay.
• 2026-03-26: Bổ sung Reading Rule để giữ ENG_Navigation_00_Overview.md là file đọc đầu tiên cho feature navigation, còn file này chỉ giữ owner boundary.
• 2026-03-25: Bổ sung Destination Boundary Rule để tách rõ Hôm nay khỏi Tiến độ, tránh trùng next action với analytics/history.
• 2026-03-25: Bổ sung Shell Layer Rule để chốt Global Today -> Program Workspace -> Deep Object, và làm rõ Home là cross-program hub chứ không phải pseudo-program workspace.
• 2026-03-14: Bổ sung Cross-layer Owner Map, chốt Home là owner của 5 retention hooks, và đồng bộ page-role contract với lifecycle contract mới.
• 2026-03-11: Khởi tạo contract ngắn cho page roles để đồng bộ Home, Program Landing, Exercise Bank, LM, CM, và Vocabulary theo nguyên tắc mỗi page một câu hỏi quyết định chính.