File and image uploader
Drag-and-drop, picker, progress, retry, preview, metadata, permissions and attachment behavior.
Shared componentFuture Spec 16 →Current-state summary
File and image uploader appears across the current product but is not yet governed as one fully documented reusable component. Record Files supports upload and a grid, inspiration uses image tiles, Notes mentions attachments and Applications require documents, but one upload queue and validation contract is not visible.
Interface inventory
Anatomy and verified behavior
Verification states separate observed behavior from requirements or assumptions.
| Element | Current behavior | Verification |
|---|---|---|
| Canonical interaction | Support picker and drag/drop with explicit accepted types, size/count limits and destination context. Create upload queue with progress, cancel, retry, checksum/deduplication and failure reason. Collect title/type/visibility where required; image previews preserve orientation and originals; security scanning occurs before availability. | Required reusable contract |
| Data contract | Store immutable File object, version, checksum, media metadata, uploader, source, visibility and typed links; binary storage is separate from business Document meaning. | Required shared storage and API behavior |
| Accessibility | Drop zone also provides labelled file input; queue progress and errors are announced; previews have meaningful alt text or decorative designation. | Required before component is approved for reuse |
| Reuse inventory | Record Files, Project inspiration, Internal Notes, Application Documents, receiving photos, delivery proof, Credentials, Project Presentations | Known current and future consumers |
| Current inconsistencies | Different surfaces imply separate upload patterns. Progress/retry and malware-processing states are not evidenced. Visibility defaults and metadata requirements vary. | Observed or identified correction work |
User journeys
Current flows
Use File and image uploader
- Render from the shared component registry
- Load canonical value and configuration
- Accept keyboard, pointer or assistive-technology input
- Validate and normalize
- Persist canonical value with provenance
- Render the same meaning in profiles, grids, filters, exports and integrations
State model
Current and expected states
Value can be entered or selected with a visible label.
Must provide a visible focus indicator without layout shift.
Must distinguish unavailable input from view-only canonical value.
Requirement is communicated in label, schema and validation—not colour alone.
Inline message explains the problem and preserves the user’s input where safe.
Async work prevents duplicate commands and remains announced.
Null, empty string, zero and empty collection retain distinct meanings.
Product rules
Non-negotiable boundaries
- Build once and reuse the same component, schema and formatter in every Workspace experience.
- Display formatting is separate from canonical storage.
- Every value has a stable field key, type, validation, privacy classification and version.
- Client validation improves usability; server validation remains authoritative.
- Equivalent values render consistently in forms, grids, profiles, filters, exports, notifications and documents.
- Support picker and drag/drop with explicit accepted types, size/count limits and destination context.
- Create upload queue with progress, cancel, retry, checksum/deduplication and failure reason.
- Collect title/type/visibility where required; image previews preserve orientation and originals; security scanning occurs before availability.
Known current limitations · 3 mapped
What is missing, broken or unverified
Future Spec 16 owns closure →- Different surfaces imply separate upload patterns.
- Progress/retry and malware-processing states are not evidenced.
- Visibility defaults and metadata requirements vary.
Future alignment
Required evolution
- 01Promote this pattern into the approved component library.
- 02Replace local copies incrementally and retain migration adapters only where required.
- 03Add automated interaction, validation, accessibility and serialization tests.
- 04Track reuse across: Record Files, Project inspiration, Internal Notes, Application Documents, receiving photos, delivery proof, Credentials, Project Presentations.
Current baseline
Acceptance record
- The component has one public API and canonical data contract.
- All required states are documented and tested.
- Formatting and validation are consistent across every consumer.
- Keyboard and screen-reader testing passes.
- Existing inconsistent copies have an owner and migration plan.
Reverse-spec completeness
Documentation coverage
The interface is still changing, so visual evidence and repository tracing remain intentionally incomplete.
Purpose and user outcome
DocumentedRoles and access
DocumentedRoutes and entry points
DocumentedPage and component anatomy
DocumentedFields and displayed data
DocumentedPrimary actions
DocumentedForms and validation
DocumentedStates and transitions
DocumentedEmpty, loading and error states
DocumentedResponsive behavior
PartialAccessibility behavior
PartialActivity and audit events
PartialData sources and persistence
DocumentedNotifications and automation
PartialKnown defects and limitations
DocumentedReusable component dependencies
DocumentedFuture-spec conflicts
PartialVisual and repository evidence
DeferredAcceptance of current baseline
Documented