Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/20-ui-ux-design-system.md

@@ -0,0 +1,204 @@
+# UI/UX design system
+
+## Design direction
+
+ItWorx Knowledge Hub should feel like a focused professional technical workspace:
+
+- calm;
+- compact without being cramped;
+- legible for long documents;
+- fast;
+- consistent;
+- trustworthy;
+- restrained in motion and decoration.
+
+It should not look like a generic admin template or an overloaded analytics dashboard.
+
+## Brand direction
+
+Use the ItWorx identity with two controlled accents:
+
+- a clear light blue for navigation/knowledge actions;
+- one consistent green for positive/project accents.
+
+The application must also work in monochrome/high-contrast contexts. Semantic states
+(error, warning, success) may use distinct accessible colors but must not redefine the
+brand.
+
+Exact tokens are implemented and contrast-tested in M1. Avoid hardcoded colors inside
+components.
+
+## Typography
+
+- UI: modern highly legible sans-serif.
+- Code: reliable monospace.
+- Long-form body target: 70–85 characters per line.
+- Default body size at least 16 CSS px.
+- Headings use a restrained scale and predictable spacing.
+- Do not use all-caps for long labels.
+
+Prefer system or openly licensed bundled/web-safe fonts. The product must not require an
+external font CDN.
+
+## Spacing and density
+
+Use a 4 px base grid with common increments 4/8/12/16/24/32.
+
+Two density modes may be considered later; v1 has one balanced default. Tree rows and
+buttons must remain large enough for touch targets.
+
+## Layout tokens
+
+- Header: approximately 56 px.
+- Left navigation: 280 px default, 224–420 px resizable.
+- Context panel: 300 px default, collapsible.
+- Document max line width independent of center pane width.
+- Mobile breakpoint based on usable layout, not device names.
+- Avoid horizontal page scrolling except deliberate code/table containers.
+
+## Core components
+
+- App shell
+- Navigation tree
+- Breadcrumbs
+- Global search/command palette
+- Page header
+- Document renderer
+- Markdown editor and split preview
+- Table of contents
+- Metadata panel
+- Backlink/relations list
+- Tag input
+- Status badge
+- Project card/list
+- Timeline
+- ADR state/lineage
+- Runbook structure/validation
+- Revision list/diff
+- Attachment uploader/list
+- Import plan/report
+- Data table with cursor pagination
+- Dialog, sheet and confirmation
+- Toast plus persistent error summary
+- Skeleton/loading indicator
+- Empty state
+- Conflict-resolution panel
+
+Build shared primitives; avoid route-specific visual inventions.
+
+## Navigation tree behavior
+
+- Lazy load children.
+- Expand/collapse with keyboard.
+- Maintain expanded state per user/device.
+- Support drag/move only when accessible alternatives exist.
+- Context menu has an explicit button, not right-click only.
+- Current page is indicated semantically and visually.
+- Long titles truncate with accessible full-title access.
+- Moving a subtree shows destination and impact before commit.
+
+## Editor
+
+Desktop modes:
+
+- write;
+- split;
+- preview.
+
+Mobile modes are separate tabs, never a squeezed split view.
+
+Editor requirements:
+
+- clear draft/published state;
+- last autosave time;
+- save/publish action;
+- change summary;
+- outline navigation;
+- internal-link chooser;
+- upload insertion;
+- accessible keyboard shortcuts;
+- conflict banner and merge flow;
+- no toolbar that steals focus unpredictably.
+
+A command palette can accelerate formatting and page creation but is not required to
+complete basic tasks.
+
+## Feedback states
+
+### Loading
+
+Use stable skeletons for page/tree/list layouts. Do not block the entire shell for one
+panel.
+
+### Empty
+
+Explain what belongs here and provide one relevant action.
+
+### Error
+
+- state what failed;
+- preserve user input;
+- show retry or recovery;
+- include correlation ID in expandable technical details;
+- do not expose stack traces.
+
+### Conflict
+
+Distinguish:
+
+- server version;
+- local draft;
+- common/base revision.
+
+Never present “last save wins” as success.
+
+### Success
+
+Use subtle confirmation. Do not rely only on transient toast for important operations such
+as import, backup or token creation.
+
+## Responsive behavior
+
+### Desktop
+
+Three-pane reading where space allows.
+
+### Tablet/narrow desktop
+
+Context panel becomes a sheet. Navigation can collapse.
+
+### Mobile
+
+- one pane;
+- bottom/top actions within thumb reach;
+- no hover-only controls;
+- editor toolbar scrolls or groups;
+- dialogs avoid overflowing viewport/keyboard;
+- tables transform or use contained horizontal scrolling.
+
+## Dark mode
+
+- user-selectable plus system preference;
+- no flash of wrong theme;
+- syntax highlighting and Mermaid remain readable;
+- images/diagrams retain borders where needed;
+- contrast verified independently.
+
+## Motion
+
+- brief functional transitions only;
+- respect `prefers-reduced-motion`;
+- no parallax, continuous decorative movement or animation blocking input;
+- loading indicators must not cause layout shift.
+
+## Content tone
+
+Dutch UI copy is direct and professional:
+
+- “Pagina maken”
+- “Wijzigingen publiceren”
+- “Versieconflict”
+- “Import controleren”
+- “Back-up herstellen”
+
+Avoid anthropomorphic AI wording because AI is not part of the product.