Files
jaime.meza b9a194f7c5 docs: reorganize site structure using Diátaxis framework
- Group hub-documentation into explanation/, how-to/, and reference/ per Diátaxis
- Move ifs-integration.md to new hoist-hub/ category
- Add contributing/ category with Diátaxis framework explainer
- Move tutorial-basics and tutorial-extras under docusaurus-guide/
- Rewrite docs/intro.mdx as site entry point with category navigation
- Update all doc titles to reflect their Diátaxis type
- Add HOIST logo to homepage hero and fix Get Started link
2026-06-18 14:50:15 -05:00

130 lines
3.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.