Frontend Design Foundation

Direction

The DCM frontend now follows a compact command-deck direction:

Use frontend/src/design-foundation.css as the single token source for:

Do not hardcode new palette or spacing values in component styles when a token already exists.

The top bar is sticky and should remain compact under all breakpoints.
Documents and viewer operate as a two-pane layout on desktop and collapse to one pane on narrower screens.
Search controls are split into two rows: primary full-text search with actions, then secondary metadata filters.
Pagination is rendered as a dedicated compact strip directly above the document card grid.
Toolbar rows should keep critical actions visible without forcing large vertical gaps.
Settings sections should preserve dense form grouping while remaining keyboard friendly.

Global input, select, textarea, and button styles are defined once in frontend/src/styles.css.
Checkbox and radio controls must be styled through explicit input[type='checkbox'] and input[type='radio'] rules, not generic text-input selectors.
Variant button classes (secondary-action, active-view-button, warning-action, danger-action) are the only approved button color routes.
Tag chips, routing pills, card chips, and icon buttons must stay within the compact radius and spacing scale.
Focus states use :focus-visible and tokenized focus color to preserve keyboard discoverability.

Use rise-in for section entry and pulse-border for card selection emphasis.
Keep transitions brief and functional.
Avoid decorative animation loops outside explicit status indicators like terminal caret blink.

Keep processing log headers in strict arrival order when typing animation is enabled.
Buffer newly discovered entries and reveal only one active line at a time while it types.
Do not render queued headers before their animation starts, even when polling returns batched updates.
Preserve existing header content format and fold/unfold detail behavior as lines are revealed.

Document previews and thumbnails must load through authenticated fetch flows in frontend/src/lib/api.ts, then render via temporary object URLs.
Runtime auth should prefer per-user token resolution (setApiTokenResolver and setRuntimeApiToken) rather than static build-time token distribution, with VITE_API_TOKEN used only as fallback compatibility.
Direct window.open calls for protected media endpoints are not allowed because browser navigation requests do not include the API token header.
Download actions for original files and markdown exports must use authenticated blob fetches plus controlled browser download triggers.
Revoke all temporary object URLs after replacement, unmount, or completion to prevent browser memory leaks.
DocumentViewer iframe previews must be restricted to safe MIME types and rendered with sandbox, restrictive allow, and referrerPolicy="no-referrer" attributes. Active or script-capable formats must not be embedded inline.

When adding or redesigning a UI area:

Start from existing tokens in frontend/src/design-foundation.css.
Add missing tokens in frontend/src/design-foundation.css, not per-component styles.
Implement component styles in frontend/src/styles.css using existing layout and variant conventions.
Validate responsive behavior at 1240px, 1040px, 760px, and 560px breakpoints.
Verify keyboard focus visibility and text contrast before merging.

Keep helper copy in settings short and plain language, especially on advanced model and threshold controls.
Prefer one concise hint per advanced control that explains practical impact rather than internals.
In the Workspace settings block, keep processing-log controls visually separated from default path and tag behavior.
Processing-log hints must explicitly state they affect logs and retention behavior, not document metadata values.