Initial commit

doc/frontend-design-foundation.md

@@ -0,0 +1,49 @@
+# 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.
+- 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`.
+- 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.