PavingOS Design Contract

PavingOS Design Contract (MVP)

Version: 1.0

Status: Authoritative

Applies to: All user-facing surfaces

Audience: Product, Design, Engineering, AI coding agents

1. Purpose of This Contract

This document defines the experience rules for PavingOS.

It exists because:

No visual designs or prototypes exist yet

UX quality is a core product differentiator

Engineering alone cannot infer correct experience

AI coding agents require explicit taste boundaries

This contract does not specify visuals.

It specifies how the product must feel and behave.

Any implementation that violates this contract is incorrect, even if technically functional.

2. Authority & Precedence

Artifact Hierarchy

PRD — What problem we are solving and why

Design Contract — How the product must feel and behave

Engineering Spec — How the system is implemented

Conflict Resolution

When conflicts arise:

Data integrity > UX polish

Field usability > office convenience

Design Contract > ad-hoc UI decisions

3. Core Design Philosophy

PavingOS is a replacement for outdated, overburdened construction software.

It must feel:

Simple

Intuitive

Calm under pressure

Trustworthy in unreliable conditions

The product should feel closer to:

Duolingo (guided progress)

Chess.com (state clarity)

ChatGPT (single interaction surface)

Slack (reliable async history)

And not like:

ERP software

Traditional construction CRMs

Dashboard-heavy admin tools

4. Design Laws (Non-Negotiable)

These laws apply to all surfaces, unless explicitly exempted.

Law 1: One Obvious Next Action

At any moment, the user should know exactly what to do next without thinking.

Rules

Every screen has one primary action

Secondary actions must be visually subordinate

No screen may present multiple competing “main” actions

Failure mode

If a user hesitates or asks “what now?”, the design has failed.

Law 2: State Is the Interface

The UI must reflect system state without explanation.

Rules

UI changes based on state, not navigation

Status is visible, not hidden behind menus

Users should never need to “check” whether something worked

Examples

Job not started → “Start Job”

Job in progress → “Complete Job”

Offline → visible but non-blocking indicator

Law 3: One Interaction Primitive per Surface

Each surface optimizes for one mental model.

Rules

Do not mix interaction paradigms on the same surface

Do not bring admin patterns into field workflows

Surfaces

Field App: action-driven (buttons, camera, quick inputs)

Office App: form-driven (inputs, tables, review flows)

If a surface requires multiple mental models, it must be split.

Law 4: Immediate Local Success

User actions must succeed locally and instantly.

Rules

No field action blocks on network calls

Success feedback must be immediate

Sync is a background concern

Failure mode

Any loading spinner after a foreman action is suspect.

Law 5: History Is the Product

Users trust systems that remember.

Rules

Append-only history preferred over editing

Past actions are visible and auditable

Corrections are additive, not destructive

This builds trust and simplifies mental models.

Law 6: Progress Beats Configuration

The product should pull users forward.

Rules

Foremen never configure

Defaults must be aggressive and safe

Setup belongs in the office app, not the field

If a foreman must “set something up” to do work, the design has failed.

Law 7: Friction Is Taxed

Every required interaction has a cost.

Rules

If it doesn’t create immediate value, remove it

Fast path must always be the default path

Optional inputs must stay optional

5. Application Surfaces

5.1 Field App (Foreman)

Environment

Loud

Dirty

Rushed

Unreliable connectivity

Primary Goal

Capture reality with minimal friction

UX Priorities (in order)

Speed

Reliability

Zero cognitive load

Hard Constraints

One-handed use

Large touch targets (≥44px)

High contrast

No dense layouts

No required typing for core actions

5.2 Office App (Estimator / Ops)

Environment

Calm

Desktop / tablet

Time to think

Primary Goal

Accuracy and clarity

UX Priorities

Financial correctness

Auditability

Efficiency for repeat tasks

6. Interaction Budgets (Hard Limits)

Tap Budget (Field App)

Any flow exceeding these limits is invalid.

Time Budget

Any core foreman action must complete in <10 seconds

Entire “start → execute → complete” happy path must be doable in <60 seconds, offline

7. Offline Experience Rules

Offline is a first-class UX state.

Rules

Offline actions always succeed locally

Sync status is visible but never blocking

Errors are actionable, not modal

User can continue working regardless of sync state

No destructive errors in the field app.

8. Event-to-UX Mapping Contract

Every backend event must correspond to a deliberate UI action.

No hidden or automatic events without user intent.

9. Forbidden Patterns (Explicit Anti-Patterns)

These are not allowed in MVP:

Multi-tab navigation in field app

Dense tables on mobile

Nested modals

Hover-dependent interactions

Configuration screens for foremen

Blocking errors during execution

Dashboard-first layouts

10. Foreman Golden Path (Canonical)

A foreman must be able to:

Open app

Unlock with PIN

See assigned job

Start job

Add photo

Log hours

Complete job

All steps must:

Work offline

Confirm instantly

Leave an auditable history

If this path is not effortless, the product is wrong.

11. Change & Evolution

This contract will evolve.

Changes must:

Be explicit

Be reviewed across Product, Design, Engineering

Not silently invalidate existing behavior

Visual design systems may be added later without changing this contract.

12. How This Contract Is Used

For Humans

Design reviews

UX validation

Product decision-making

For AI Coding Agents

Agents must be instructed:

“Implement UI strictly according to the PavingOS Design Contract.

Do not invent flows, configuration, or navigation beyond what is explicitly allowed.”

Final Statement

This contract exists to ensure PavingOS feels:

Modern

Calm

Trustworthy

Purpose-built

Not like the software it replaces.

ChatGPT screens