transcription/docs/ui/README.md

UI Behavioral Contracts

Purpose

This directory defines the current user-facing behavior of the NiceGUI application. It records what each page is for, which routes and actions it exposes, what information it presents, and how success, empty, validation, and failure states behave.

These documents are written for maintainers and AI contributors. They are behavioral contracts, not historical implementation notes and not substitutes for the database schema.

Current Page Contracts

• Home
• Documents
• People
• Jobs
• Sources

NiceGUI registers the routes shown in each contract without the /ui prefix. The application mounts NiceGUI under /ui, so /documents in page code is served to a browser as /ui/documents.

Authority Hierarchy

When documents disagree, use this order:

1. User-facing page intent and accepted behavior: the page contracts in this directory.
2. Visual and interaction styling: UI Style Guide.
3. UI dependency and ownership boundaries: UI contributor instructions.
4. Durable failure behavior: Error Handling invariant.
5. Durable AI evidence behavior: Digital Evidence and AI Processing Provenance.
6. Data definitions and relationships: current models plus the V4 schema.
7. Planned behavior changes: the applicable V4.x scope and implementation documents.
8. Implementation truth: current code and tests.

If code intentionally changes accepted page behavior, update the corresponding page contract in the same change. If code accidentally differs, correct the implementation rather than rewriting intent to match a defect.

Contract Contents

Each page contract contains:

1. Purpose and user goals.
2. Registered routes and navigation context.
3. List, detail, and form behavior.
4. Editable and system-managed information.
5. Validation, empty, loading, and failure states.
6. A concise acceptance checklist.
7. Current implementation and test anchors.
8. Known limitations and deferred work.

Maintenance Rules

• Describe current accepted behavior in present tense.
• Do not mix an obsolete “first release” design with current behavior.
• Keep future changes in versioned scope documents and link to them from a Deferred Work section.
• Do not reproduce the complete database field inventory here; include only fields that affect page behavior.
• Keep service, file, and test anchors current.
• Do not create separate current-state, target-state, and traceability copies of the same contract.
• Keep cross-page visual rules in the UI Style Guide instead of repeating them on each page.
• Keep database joins such as DocumentPerson and JobSource in schema/architecture documentation unless they directly affect a page interaction.

Current Baseline

These contracts describe the V4 baseline with completed V4.1 behavior and V4.2 evidence/provenance behavior. Draft V4.3 Settings/page-reordering changes are not described as current behavior.