205 lines
5.0 KiB
Markdown
205 lines
5.0 KiB
Markdown
# 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.
|