# Frontend Design Foundation

## Direction

The DCM frontend now follows a compact command-deck direction:
- dark layered surfaces with strong separation between sections
- tight spacing and small radii to maximize information density
- consistent control primitives across buttons, inputs, selects, and panels
- high-legibility typography tuned for metadata-heavy workflows

## Token Source

Use `frontend/src/design-foundation.css` as the single token source for:
- typography (`--font-display`, `--font-body`, `--font-mono`)
- color system (`--color-*`)
- spacing (`--space-*`)
- radii and shadows (`--radius-*`, `--shadow-*`)
- interaction timing (`--transition-*`)

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

## Layout Principles

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

## Control Standards

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

## Motion Rules

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

## Processing Log Timeline Behavior

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

## Authenticated Media Delivery

- Document previews and thumbnails must load through authenticated fetch flows in `frontend/src/lib/api.ts`, then render via temporary object URLs.
- Runtime auth uses server-issued per-user session tokens persisted with `setRuntimeApiToken` and read by `getRuntimeApiToken`.
- Static build-time token distribution is not supported.
- 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.

## Extension Checklist

When adding or redesigning a UI area:
1. Start from existing tokens in `frontend/src/design-foundation.css`.
2. Add missing tokens in `frontend/src/design-foundation.css`, not per-component styles.
3. Implement component styles in `frontend/src/styles.css` using existing layout and variant conventions.
4. Validate responsive behavior at `1240px`, `1040px`, `760px`, and `560px` breakpoints.
5. Verify keyboard focus visibility and text contrast before merging.

## Settings UX Copy

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