77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# 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 is cookie-backed; valid sessions are reused by browser reload and tab reuse while the `dcm_session` cookie remains valid.
|
|
- 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.
|