itworx-knowledge-hub-Public/docs/20-ui-ux-design-system.md

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.