Add dashboard layout plan and scenario validation rules documentation

specifications/dashboard_layout.md

@@ -0,0 +1,45 @@
+# CalMiner Dashboard Layout Plan
+
+Last updated: 2025-11-09
+
+This document describes the intended layout structure for the CalMiner homepage/dashboard template.
+
+## Page Goals
+
+- Provide a concise overview of key project and scenario metrics immediately after sign-in.
+- Offer quick actions for creating or navigating to core workflows (projects, scenarios, data uploads).
+- Surface recent activity in a scan-friendly, responsive layout that works on desktop and tablet.
+
+## Layout Structure
+
+1. **Hero Header**
+
+   - Title block with optional welcome message and current environment badge.
+   - Primary CTA button group (e.g., "New Project", "Import Data").
+   - Optional quick filter chips for project categories.
+
+2. **Summary Metrics Row**
+
+   - Four metric cards showing: total projects, active scenarios, pending simulations, last import timestamp.
+   - Cards adapt to a two-column grid on screens < 960px.
+
+3. **Recent Activity Panels**
+
+   - Left column (2/3 width) displays a table of recent projects with status, updated timestamp.
+   - Right column (1/3 width) hosts scenario alerts (validation conflicts, approaching deadlines) in a stacked list.
+
+4. **Secondary Widgets**
+   - Simulation pipeline status timeline (if data present) or placeholder guidance.
+   - Documentation and support links card.
+
+## Responsiveness
+
+- Desktop: two-column layout for activity panels and secondary widgets.
+- Tablet: stacks columns vertically while keeping metric cards in two columns.
+- Mobile: single-column flow; CTA buttons collapse into a vertical stack.
+
+## Implementation Notes
+
+- Reuse existing `.card`, `.page-header`, and `.container` classes from `static/css/main.css`.
+- Introduce specialized dashboard classes (e.g., `.dashboard-metrics`, `.dashboard-grid`) scoped within a new `static/css/dashboard.css` file if needed.
+- Provide placeholder content for areas where backend data integrations are pending (e.g., empty state messages).