transcription/docs/ui/README.md

UI Documentation

This folder contains UI-focused design and mapping documents that connect the database schema to user-facing workflows.

Document Types

user-journey.md

A product and UX contract for a user-facing entity.

Use this document to describe:

• what the user is trying to do
• which screen or action starts the workflow
• which fields the user sees and edits
• validation rules
• expected success and failure outcomes
• where the user goes next

schema-mapping.md

A field-level mapping between schema, UI, and implementation.

Use this document to describe:

• the authoritative schema fields for an entity
• which fields are shown, hidden, editable, or system-managed
• current implementation behavior
• intended target behavior
• implementation gaps between current code and intended UX

acceptance-criteria.md

An implementation-ready checklist for CRUD behavior and quality gates.

Use this document to describe:

• testable acceptance statements by flow (Create, Read, Update, Delete)
• success and failure behaviors
• first-release constraints
• cross-criteria quality gates

traceability-matrix.md

A criteria-to-code mapping that identifies implementation anchors and status.

Use this document to describe:

• acceptance criteria group to implementation file mapping
• delivery status (implemented, partial, planned)
• ordered implementation priorities

Organization Rules

• Store documents under docs/ui/entities/<entity-name>/.
• Create both user-journey.md and schema-mapping.md for user-facing entities.
• Create acceptance-criteria.md for user-facing entities.
• Create only schema-mapping.md for supporting tables that do not currently have standalone UI.
• Keep one shared traceability-matrix.md under docs/ui/entities/ to map criteria to implementation anchors.
• Keep top-level docs/ reserved for core architecture, requirements, schema, and system-wide reference material.

Current Entity Plan

User-facing entities:

• document
• person
• source
• job

Supporting entities:

• document-person
• job-source

Relationship to Core Docs

These UI docs complement, but do not replace:

• docs/schema_v2.md
• docs/requirements_v2.md
• docs/architecture_v2.md

When there is a conflict:

• schema definitions come from the database model and schema docs
• user interaction intent comes from the user-journey docs
• implementation truth comes from code and is recorded in schema-mapping docs as current-state evidence