Skip to content

Source truth: - UX Principles - Vision and Product Principles - Kernel Contract - Protected Action Contract

Presentation Guidance

This page explains how the BooksPlus 3 Avalonia presentation layer should support canonical product and accounting rules.

Boundaries

  • Avalonia views and view models should not own accounting rules.
  • View models may prepare user input, expose state, and coordinate commands, but application services decide consequential behavior.
  • UI validation should guide users early, but domain and application validation remain authoritative.
  • Presentation code should not write ledger effects, change period state, bypass protected actions, or create audit records directly.

State display

Views should make important states visible without forcing users to inspect details first.

Examples include:

  • transaction status: draft, reviewed, posted, reversed;
  • period status: planned, open, soft closed, hard closed, reopened;
  • close status: blocked, warning, ready for review, approved, finalized;
  • evidence status: missing, attached, superseded, reviewed;
  • report status: current, stale, generated, exported.

Consequential actions

Consequential actions should follow a consistent presentation pattern:

  1. Show the current state.
  2. Show the proposed action.
  3. Summarize impact and affected records.
  4. Ask for reason, approval, or step-up confirmation when required by policy.
  5. Call the application service.
  6. Show the result, audit reference, and next available actions.

Exceptions and validation

Error and exception displays should identify:

  • what failed;
  • why it matters;
  • where the user can inspect the related object;
  • whether the issue blocks completion;
  • what action can resolve or explain it.

Avoid exposing exception class names, persistence errors, or low-level validation language as the primary user message.

Data-heavy screens

Accounting screens may be dense when density helps review.

Registers, tables, dashboards, and exception queues should support:

  • keyboard-friendly entry and navigation;
  • sorting, filtering, and search;
  • stable columns for status, date, period, amount, source, and owner where relevant;
  • drilldown from summary to detail;
  • returning to the prior context after drilldown.

Long-running work

Imports, valuation rebuilds, close checks, report generation, backup restore, and similar operations should expose progress and final result state.

Users should be able to tell whether the work is queued, running, completed, failed, canceled, or requires attention.

Avalonia implications

  • Prefer view models that expose business-shaped state and commands.
  • Keep presentation models separate from persistence models.
  • Use reusable UI patterns for status banners, action summaries, reason capture, exception lists, and evidence links.
  • Keep keyboard workflows efficient for repetitive accounting entry.
  • Use visual styling to clarify state and priority, not to decorate accounting workspaces.