Hint System · Planning

Context

Handoff hand-hint-system: A implement object-level hint registry + delivery policy + translation pipeline · ALL content comes from B-owned JSON files. ใช้ใน Dashboard purpose tooltips · Wizard step subtitles · Enterprise Upload panel hints · Cases portal hints · Knowledge lookup.

docs/kb/data/page_purpose.json30 pages · name/what/when in TH/EN/ZH

docs/kb/data/audience_entrypoints.jsonaudience personas + entrypoint labels

docs/kb/data/lexicon.json80 entries · trilingual definitions · glossary popover

docs/kb/data/premium_wizard.jsonsteps[*].honest_note · step purpose

docs/kb/data/hybrid_intake_workspace.json8 panel purposes

docs/kb/data/dashboard_contract.jsondashboards[*].purpose · honest_note

A-owned Runtime Boundary

B owns (read-only for A)

All hint content (name_th/en/zh · what · when · purpose · honest_note)
Trilingual parity enforcement
Sensitive-surface markers on specific hints
Lexicon term definitions

A owns (this runtime)

Hint registry (maps object_id → B content path)
Delivery policy engine (first-time / on-demand / always)
User-seen state (per-user per-hint dismiss log)
Trigger detection (hover · click · focus · viewport)
Render component (tooltip / popover / banner)
Fallback chain (zh missing → en → th)

Scope

Hint registry: hints table · maps object_id (CSS selector or component id) → content_ref (path into B JSON)
Content loader: fetch B JSON at startup · normalise to shared shape · cache in memory
Delivery policy engine: 3 modes — first-time (dismiss after view) / on-demand (hover/click) / always-available (icon badge)
User-seen state: user_hint_state table · per-user dismiss log
Trigger detection: hover debounce / click / focus / viewport IntersectionObserver
Render components: Tooltip (short) · Popover (medium + link) · Banner (long · dismissible)
Translation fallback: zh → en → th chain · never show key
Sensitive-hint domain review: hints on sensitive UI objects require domain expert sign-off
Analytics: hint_shown / hint_dismissed / hint_clicked events (for UX refinement)

ER Diagram

Hint System · registry + state + content cache

Field Mapping — Hint Registry

Source (B)	A Registry Target	Render Style	Delivery	Binding	Notes
page_purpose.pages.{id}.name_{lang}	Page header title label	Banner	always-available	mapped-not-bound	i18n dict · fallback chain
page_purpose.pages.{id}.what_{lang}	Page subtitle / intro	Banner	always-available	mapped-not-bound	Visible without interaction
page_purpose.pages.{id}.when_{lang}	"When to use" helper	Popover	on-demand	mapped-not-bound	Shown on ? icon click
premium_wizard.steps.{n}.purpose_{lang}	Step subtitle in wizard	Tooltip + inline	always-available	placeholder	Wizard runtime consumes
premium_wizard.steps.{n}.honest_note_{lang}	Step footer caption	Banner	always-available	placeholder	Verbatim render · no edits
dashboard_contract.dashboards.{id}.purpose_{lang}	Dashboard header tooltip	Tooltip	on-demand	mapped-not-bound	On info-icon hover
dashboard_contract.dashboards.{id}.honest_note	Chart footer caption	Banner	always-available	mapped-not-bound	requires_human_review=true → yellow banner
hybrid_intake_workspace.workspace_panels.{id}	Panel entry hint	Tooltip	first-time	placeholder	8 panels
lexicon.terms.{id}.short_def_{lang}	Glossary popover on term hover	Popover	on-demand	mapped-not-bound	Auto-detect terms in text
audience_entrypoints.personas.*	Audience label on nav card	Badge + tooltip	always-available	mapped-not-bound	Product + governance personas

API Sketch

GET/api/hints/lookup?object_id=dashboard.gmv-daily&lang=th

Resolve hint for an object · returns content + style + delivery

// response { "object_id": "dashboard.gmv-daily", "content": { "title": "GMV รายวัน", "body": "ยอดขายรวมต่อวัน · เป้า ฿1.5M · warn <฿1.2M", "footer": "source: kpi_targets Layer H" }, "render_style": "tooltip", "delivery_mode": "on-demand", "sensitive_flag": false, "fallback_used": false }

POST/api/hints/event

Log hint interaction (shown · dismissed · clicked)

// request { "hint_id": "h-dashboard-gmv", "event": "dismissed", "locale": "th", "session_ref": "SESS-..." }

POST/api/admin/hints/reload

Trigger content cache reload from B JSON · admin only

Sequence Flow first-time hint delivery + dismiss

First-time hint on wizard step · lang=th

Dependencies

Upstream

Auth (user_id for per-user state)
Postgres
B data files readable at deploy
Content loader (startup bootstrap)

Downstream

Dashboard Runtime (tooltips + honest-note banners)
Wizard Runtime (step subtitles)
Tenant Runtime (panel entry hints)
All UIs with glossary auto-detect

Approval Gates

gate-sensitive-hint Domain expert sign-off for hints on sensitive surfaces (e.g., mood-smart-flow copy)
gate-content-refresh Admin-only trigger for re-loading B content cache
gate-no-a-handtyped CI check: no inline hint content in A code (only via registry)

Risks

A-side developer types hint content inline (bypasses B)

High

CI lint rule: forbid string literals matching "hint" pattern · all hint components require registry ref

Trilingual fallback displays key instead of text

Med

Fallback chain zh→en→th · test in all locales · CI asserts at least one present per hint

B content hot-reload drops active hints

Low

Hot-reload is additive · deletions require soft-remove flag · observable via hint_events

Hint spam (every object shows hint first-time = overwhelming)

Med

Throttle first-time hints to 1-per-minute · user-level max 3 per session

Definition of Done

Registry + loader + cache operational
3 render components (tooltip/popover/banner) deployed
3 delivery modes (first-time/on-demand/always) tested
Trilingual fallback verified in all 3 langs
Per-user dismiss state persists across sessions
CI lint prevents inline hint content
Analytics events emitted and queryable
Sensitive-hint path requires domain sign-off

Deferred

In-product hint editor (admin UI for content edits — B owns content)
A/B test different hint copy (experimentation layer later)
Voice-read hints (accessibility later)
Gamified "onboarding tour" mode

Hint System 08 · object-level hints · delivery policy · trilingual · source from B only