Initial public release

docs/UI_DESIGN_SYSTEM.md

@@ -0,0 +1,109 @@
+# GeoIntel Atlas Workbench
+
+## Purpose
+
+The Atlas Workbench is the visual and interaction system for GeoIntel. It
+keeps the product map-first, task-oriented and understandable without hiding
+source authority, observation time or GIS limitations.
+
+The redesign was developed in Stitch under:
+
+- project: `GeoIntel Complete Workbench Redesign`
+- project id: `18332842433441398219`
+- design system: `GeoIntel Atlas Workbench`
+- design-system asset: `4667932515738184526`
+- Map Explorer screen: `c24113d1f1474c91b332b2365be24993`
+- Sources screen: `239796f2d66a44e7983e5fc588305ff8`
+- AI Questions screen: `246aa57bbe974861885325ff9d10c6bd`
+- Quality screen: `06b4b69387d847a0bba33c6953563860`
+- Image Analysis screen: `200a196f4e524c979167e40905ae87f2`
+- Downloads screen: `f6d91a48e98141bb94f680f626078a1e`
+- Status and Administration screen: `3d685f83c61d4e9687bdfdf608220b26`
+
+The React implementation remains the source of truth for behavior. Stitch is
+the design reference for hierarchy, spacing and component treatment. Each
+primary workspace has a dedicated Stitch screen; new layout work must compare
+against the corresponding screen rather than only borrowing the color palette.
+
+## Product hierarchy
+
+1. `Kaart` is the primary workspace.
+2. `Bronnen` explains available and missing official data.
+3. `AI-vragen` answers only from persisted area evidence.
+4. `Kwaliteit` reviews stored checks and provenance.
+5. `Beeldanalyse` contains detection and segmentation workflows.
+6. `Downloads` stores and previews traceable outputs.
+7. `Status` summarizes readiness and source freshness.
+8. `Beheer` exposes provider and technical administration.
+
+The navigation rail is the only persistent workspace navigation. Duplicate
+command bars or competing shortcut rows must not be reintroduced.
+
+## Layout rules
+
+- Desktop uses an 88-pixel navigation rail and a 56-pixel context bar.
+- The normal map layout is `theme drawer / map / insight inspector`.
+- Sources uses `workspace and area / source inventory / loaded datasets`.
+- AI Questions uses `area context / conversation and composer`.
+- Quality uses `controls / result history / evidence inspector`.
+- Image Analysis uses `configuration / persisted results / QA`.
+- Downloads uses `artifact actions / export history / preview inspector`.
+- Administration uses `source category / provider status and provenance`.
+- Theme and insight rails stay stable on ultrawide displays; the map receives
+  the additional width.
+- Non-map workspaces use one task header and one primary work surface.
+- Panels scroll internally when their function requires stable surrounding
+  context.
+- Mobile navigation is horizontally scrollable. The theme list is bounded so
+  the map remains reachable early in the page flow.
+- Typography never scales with viewport width.
+
+## Visual tokens
+
+| Role | Value |
+| --- | --- |
+| Canvas | `#f5f7f6` |
+| Surface | `#ffffff` |
+| Pale context | `#eef8f5` |
+| Ink | `#162622` |
+| Muted text | `#64726f` |
+| Border | `#e1e7e5` |
+| Primary teal | `#0b6b62` |
+| Context blue | `#315d73` |
+| Attention amber | `#b46432` |
+| Error red | `#a33c39` |
+| Radius | `4px` |
+
+Body and labels use locally bundled Public Sans. Headings use locally bundled
+Manrope. The interface must not depend on a remote font request.
+
+The UI does not use gradients, decorative blobs, oversized hero sections,
+nested cards or pill-heavy status presentation.
+
+## Interaction rules
+
+- One primary action per task surface.
+- Use icons plus short labels for navigation and familiar commands.
+- `Laatste toestand / Evolutie` is a segmented control.
+- Rectangle drawing is the primary spatial-selection action.
+- Technical model, provider and provenance detail stays available through
+  explicit disclosures.
+- Empty states state the next useful action in one short sentence.
+- Unavailable data or model states remain honest and are never replaced with
+  fabricated output.
+
+## Implementation boundaries
+
+- Shared shell and navigation:
+  `frontend/src/components/shell/WorkbenchNavigation.tsx`
+- Shared visual implementation:
+  `frontend/src/styles/atlas-workbench.css`
+- Map workflow:
+  `frontend/src/components/map/MapWorkspace.tsx`
+- Empty and populated quality review:
+  `frontend/src/components/quality/QualityResultsPanel.tsx`
+- API, persistence and GIS behavior remain outside the design system.
+
+Any future visual change must retain the browser acceptance widths of
+390 pixels, 1280 pixels and 3440 pixels and must pass frontend typecheck,
+unit tests, production build and the UX browser audit.