--- sidebar_position: 2 title: How to Document 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.