Files
wiki-hoist/docs/hub-documentation/process/mockups.md
T

3.2 KiB
Raw Blame History

sidebar_position, title
sidebar_position title
2 Mockups & Screenshots

Mockups & Screenshots Documentation Standard

Mockups and screenshots are mandatory artifacts used to visually communicate screen behavior, layout, and user interactions. They must complement — not replace — written documentation and be consistent with the defined UI Flow and business logic.

Purpose and Scope

Mockups/screenshots must clearly illustrate:

  • Screen layout and structure
  • Key user interactions and navigation paths
  • Differences between List and Detail views
  • Variations across screen modes (e.g., View, Edit, Create)

Visual assets should reflect the intended final behavior, not exploratory or experimental designs unless explicitly stated.


Mockup Requirements

Level of Fidelity

High-fidelity mockups are preferred for:

  • New screens
  • Complex user interactions
  • Approval-ready specifications

Low- or mid-fidelity mockups are acceptable for:

  • Early discovery phases
  • Internal alignment or conceptual discussions

:::note Low/mid-fidelity mockups must be clearly labeled as non-final. :::

Consistency

Mockups must align with:

  • Design system / UI guidelines
  • Naming conventions used in documentation
  • Field labels, actions, and terminology defined in the spec

Any intentional deviation from standards must be explicitly documented.

Coverage

Mockups should cover, at minimum:

  • List View (default state)
  • Detail View (view-only mode)
  • Detail View (edit/create mode)
  • Empty states (no data)
  • Error or validation states (if applicable)

Screenshot Standards

When to Use Screenshots

Screenshots may be used when:

  • Documenting existing or legacy functionality
  • Validating implemented behavior against specifications
  • Providing references for enhancements or bug fixes

Quality and Clarity

Screenshots must:

  • Be clear, legible, and high resolution
  • Exclude irrelevant UI elements or personal data
  • Highlight the relevant area using annotations if needed

Annotation and Labeling

All mockups and screenshots must include:

  • Screen name and version
  • Mode or state (e.g., List, Detail – Edit)

Annotations should be used to:

  • Explain business rules
  • Clarify hidden or dynamic behavior
  • Call out permissions, validations, or conditional visibility

Annotations must be concise and consistent with written documentation terminology.


Traceability and Referencing

Each mockup or screenshot must:

  • Be referenced explicitly in the documentation (e.g., "See Mockup M-01")
  • Map clearly to documented requirements, flows, or actions

If multiple screens share similar layouts or behavior, this should be stated to avoid redundancy.


Versioning and Maintenance

Mockups and screenshots must be versioned and updated with:

  • Functional changes
  • UI changes impacting user behavior

Outdated visuals must not remain referenced in active documentation. Version history or change notes should be maintained when mockups are updated.


Tools and Formats

Format Accepted
PNG Yes
JPG Yes
Figma (embedded link) Yes

Source design files should be accessible to relevant stakeholders when possible. Screenshots embedded in documentation must preserve original aspect ratios.