# 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.