docs: migrate HOIST HUB Documentation Standard to Docusaurus

This commit is contained in:
jaime.meza committed 2026-06-18 12:54:44 -05:00
1 parent ce58a0c6e0
commit 8b30e9405b
19 files changed
+966

No files matched your search

+129
View File
@@ -0,0 +1,129 @@
---
sidebar_position: 2
title: 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.