# V2 Quest UI Documentation And Styling Guide

This guide is the authoring, implementation, and review reference for Phase 72
quest UI. It connects the quest journal, tracker HUD, map layers, wayfinding,
toasts, accessibility, localization, and validation gates that protect shipped
quest surfaces.

## Source Of Truth

- Quest journal contract:
  [QuestJournalUI_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestJournalUI_V2_Contract.json)
- Sorting and filtering contract:
  [QuestJournalSortingFiltering_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestJournalSortingFiltering_V2_Contract.json)
- Reward preview contract:
  [QuestJournalRewardPreview_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestJournalRewardPreview_V2_Contract.json)
- Pin/unpin contract:
  [QuestPinUnpin_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestPinUnpin_V2_Contract.json)
- Accessibility contract:
  [QuestUIAccessibility_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestUIAccessibility_V2_Contract.json)
- Localization contract:
  [QuestUILocalization_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestUILocalization_V2_Contract.json)
- Completion statistics contract:
  [QuestCompletionStatistics_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestCompletionStatistics_V2_Contract.json)
- Tracker HUD contract:
  [QuestTrackerHUD_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestTrackerHUD_V2_Contract.json)
- Map marker contract:
  [QuestMapMarkers_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestMapMarkers_V2_Contract.json)
- Area highlight contract:
  [QuestAreaHighlights_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestAreaHighlights_V2_Contract.json)
- Waypoint contract:
  [QuestWaypointSystem_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestWaypointSystem_V2_Contract.json)
- Breadcrumb trail contract:
  [QuestBreadcrumbTrail_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestBreadcrumbTrail_V2_Contract.json)
- Notification toast contract:
  [QuestNotificationToasts_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestNotificationToasts_V2_Contract.json)
- Difficulty indicator contract:
  [QuestDifficultyIndicators_V2_Contract.json](../../ue/Content/V2/UI/Quest/QuestDifficultyIndicators_V2_Contract.json)
- Runtime widgets:
  [V2QuestJournalScreen.h](../../ue/Source/V2UI/Public/V2QuestJournalScreen.h)
  and
  [V2QuestTrackerHUDWidget.h](../../ue/Source/V2UI/Public/V2QuestTrackerHUDWidget.h)

## Surface Inventory

Quest UI is a set of connected surfaces, not one screen. Each surface has one
primary job and should pass state to the next surface by stable ids.

| Surface               | Primary job                                                       | Required ids                                            |
| --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| Quest journal         | Inspect, filter, sort, pin, and compare quests.                   | `QuestId`, `TitleTextId`, `DescriptionTextId`           |
| Tracker HUD           | Keep the current or pinned quest visible during play.             | `TrackerId`, `TrackedQuestId`, `ObjectiveId`            |
| Map markers           | Show quest givers, objectives, and turn-ins.                      | `MarkerId`, `QuestId`, `ObjectiveId`, `TitleTextId`     |
| Area highlights       | Mark normalized search or destination regions.                    | `AreaId`, `QuestId`, `ObjectiveId`                      |
| Waypoints             | Point to current objectives in compass and screen-edge space.     | `WaypointSystemId`, `TargetId`, `TitleTextId`           |
| Breadcrumb trail      | Optional guided world path for difficulty modes.                  | `TrailId`, `QuestId`, `ObjectiveId`                     |
| Quest toasts          | Announce quest lifecycle events through the notification surface. | `ToastType`, `QuestTitleTextId`, `ObjectiveTitleTextId` |
| Difficulty indicators | Summarize recommended level, duration, and combat intensity.      | `QuestId`, `LevelLabelTextId`, `DurationLabelTextId`    |

Do not add a new quest UI surface until the job cannot be served by one of these
surfaces with clearer state or a narrower view model.

## Layout And Density

Quest UI is operational game UI. It should be dense enough to scan while the
player is deciding what to do next.

- Use cardless layout policy by default: sections, rows, dividers, and compact
  status chips are preferred over nested cards.
- Keep journal rows stable when objectives, rewards, difficulty indicators, or
  completion statistics appear.
- Keep tracker HUD dimensions stable with `MaxVisibleObjectives`,
  `ProgressFraction`, and `OverallProgressFraction`.
- Keep map, waypoint, and breadcrumb glyphs small and shape-coded; do not rely
  on color alone.
- Preserve `bControllerFirstFocus` for screen surfaces and `bGameplayInert` for
  HUD overlays.
- Preserve `bReducedMotionSafe`, `bStableDimensions`, and `bNoDecorativeCards`
  on every quest surface that declares those flags.
- In review language, call these policies controller first focus, reduced motion
  safe behavior, stable dimensions, and cardless layout policy so CI validation
  evidence is understandable outside the code.

## Quest Journal Styling

The quest journal is a work surface. It should prioritize comparison and
repeated navigation over decorative composition.

- Put filter and sort controls before the quest list. Filter by lifecycle,
  category, region, difficulty, and completion status.
- Use `EV2QuestJournalSortMode` and `EV2QuestJournalSortDirection` instead of ad
  hoc row ordering.
- Show `bPrimary`, `bPinnedToTracker`, and lifecycle state as distinct markers.
- Render objective checklist rows with `CurrentCount`, `TargetCount`,
  `bRequired`, and `bCompleted`.
- Keep reward preview rows compact and stable. Show rewards before acceptance
  only through `RewardPreviews` that opt into `bPreviewInJournal`.
- Show `CompletionStatistics`, `CompletionPercentage`, and time spent as
  secondary summary data, never as the dominant first read.

## Tracker HUD Styling

The tracker HUD is a compact status surface. It should show the next useful
objective without taking ownership of player attention.

- Track the pinned quest first, the requested quest second, and the primary
  quest third.
- Show no more than `MaxVisibleObjectives`.
- Use progress bars or rings only when `bShowProgressIndicators` is true.
- Show `QuestTitleTextId` and objective `TitleTextId` as the text anchors.
- Keep failure and completion states visible through `bQuestFailed` and
  `bQuestCompleted`.
- Keep pin and unpin controls explicit through `PinTrackedQuest`,
  `UnpinTrackedQuest`, and `bCanUnpinQuest`.

## Navigation And World Cues

World cues are optional guidance. They should support exploration without
turning every quest into a rail.

- Map markers must distinguish quest giver, objective, and turn-in types.
- Area highlights must use normalized polygon points, normalized bounds, and a
  normalized centroid.
- Waypoints must support compass and screen-edge placement with safe-area
  clamping.
- Breadcrumb trails must support `Off`, `Minimal`, and `Guided` difficulty
  modes.
- Distance, bearing, and opacity should update through state fields, not
  authored display strings.

## Notifications And Feedback

Quest toasts reuse the existing notification surface. They should be informative
without blocking play.

- Use `QuestAccepted`, `QuestObjectiveCompleted`, `QuestCompleted`, and
  `QuestFailed` notification types.
- Route quest toast actions to `ModeSpecific.QuestLog`.
- Keep toasts screen-reader announced and controller non-modal.
- Use cooldown and burst limits from `FV2QuestNotificationToastCatalog`.
- Do not create a second toast stack for quests.

## Accessibility And Localization

Accessibility and localization metadata are part of the styling contract, not
late polish.

- Use `FV2QuestUIAccessibilityDescriptor` for screen-reader summaries,
  high-contrast marker tags, and objective progress announcements.
- High-contrast markers must not be color-only. Pair color with icon, shape, or
  label state.
- Every player-facing quest UI text binding must use string ids through
  `FV2QuestUILocalizedTextBinding`.
- Use `SourceStringId` for direct quest text and `FormatStringId` plus
  `DynamicTextArguments` for progress text.
- Dynamic insertion arguments must be named, such as `CurrentCount`,
  `TargetCount`, `CompletedObjectiveCount`, `ObjectiveCount`, `ProgressPercent`,
  and `StateTextId`.
- Do not render `QuestId`, `ObjectiveId`, or fallback ids directly as display
  copy except in debug-only tooling.

## Authoring Workflow

1. Add or update quest definition text ids before touching UI layout.
2. Confirm every quest, objective, reward, map marker, waypoint, and toast uses
   stable ids.
3. Update the relevant contract if a surface gains a new field or policy.
4. Update the journal or tracker view model only when a Blueprint binding needs
   the field directly.
5. Run the validation commands in this guide before content review.
6. Include screenshots or captured UI state in review notes when the visual
   layout changes, even if only the contract checker changed.

## Review Checklist

Before content review, confirm:

- Journal rows still support active, available, completed, and failed quests.
- Sorting and filtering work without changing selected quest identity.
- Reward previews remain stable before accepting a quest.
- Pin/unpin updates the journal and tracker state consistently.
- Tracker HUD still shows only current visible objectives and progress.
- Map markers, waypoints, and breadcrumbs remain non-color-only.
- Screen-reader summaries include state and progress.
- Localization bindings use string ids and named dynamic insertion.
- Completion statistics do not overpower the selected quest content.
- Every changed surface keeps reduced-motion and cardless layout policy.
- The checker, contract, workflow, Horde metadata, and TODO evidence changed
  together.

## Validation Commands

Run these commands after changing quest UI docs, styling policy, UI contracts,
quest UI widget state, or review guidance:

```bash
python3 V2/ue/Tools/check-v2-quest-ui-documentation-style-guide.py
python3 V2/ue/Tools/check-v2-quest-journal-ui.py
python3 V2/ue/Tools/check-v2-quest-tracker-hud.py
python3 V2/ue/Tools/check-v2-quest-ui-accessibility.py
python3 V2/ue/Tools/check-v2-quest-ui-localization.py
python3 V2/ue/Tools/check-v2-ui-module.py
python3 V2/ue/Tools/check-v2-ci-workflow.py
python3 -m json.tool V2/ue/Content/V2/UI/Quest/QuestUIDocumentationStyleGuide_V2_Contract.json
python3 -m json.tool V2/ue/Build/Horde/v2-buildgraph-job.json
python3 V2/tools/validate-v2-docs.py
pnpm exec prettier --check V2/docs/modes/quest-ui-documentation-and-styling-guide.md TODOS/phase-72.md V2/ue/Content/V2/UI/Quest/QuestUIDocumentationStyleGuide_V2_Contract.json V2/ue/Build/Horde/v2-buildgraph-job.json
```