ledgerdock/doc/frontend-design-foundation.md

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.

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.