calminer/docs/developer/ui_and_style.md

UI, templates and styling

This document outlines the UI structure, template components, CSS variable conventions, and per-page data/actions for the CalMiner application.

Reusable Template Components

To reduce duplication across form-centric pages, shared Jinja macros live in templates/partials/components.html.

• select_field(...): renders labeled <select> controls with consistent placeholder handling and optional preselection. Existing JavaScript modules continue to target the generated IDs, so template calls must pass the same identifiers (consumption-form-scenario, etc.).
• feedback(...) and empty_state(...): wrap status messages in standard classes (feedback, empty-state) with optional hidden toggles so scripts can control visibility without reimplementing markup.
• table_container(...): provides a semantic wrapper and optional heading around tabular content; the {% call %} body supplies the <thead>, <tbody>, and <tfoot> elements while the macro applies the table-container class and manages hidden state.

Pages like templates/consumption.html and templates/costs.html already consume these helpers to keep markup aligned while preserving existing JavaScript selectors.

Import macros via:

{% from "partials/components.html" import select_field, feedback, table_container with context %}

Styling Audit Notes (2025-10-21)

• Spacing: Panels (section.panel) sometimes lack consistent vertical rhythm between headings, form grids, and tables. Extra top/bottom margin utilities would help align content.
• Typography: Headings rely on browser defaults; font-size scale is uneven between <h2> and <h3>. Define explicit scale tokens (e.g., --font-size-lg) for predictable sizing.
• Forms: .form-grid uses fixed column gaps that collapse on small screens; introduce responsive grid rules to stack gracefully below ~768px.
• Tables: .table-container wrappers need overflow handling for narrow viewports; consider overflow-x: auto with padding adjustments.
• Feedback/Empty states: Messages use default font weight and spacing; a utility class for margin/padding would ensure consistent separation from forms or tables.

CSS Variable Naming Conventions

The project adheres to a clear and descriptive naming convention for CSS variables, primarily defined in static/css/main.css.

Naming Structure

Variables are prefixed based on their category:

• --color-: For all color-related variables (e.g., --color-primary, --color-background, --color-text-primary).
• --space-: For spacing and layout-related variables (e.g., --space-sm, --space-md, --space-lg).
• --font-size-: For font size variables (e.g., --font-size-base, --font-size-lg).
• Other specific prefixes for components or properties (e.g., --panel-radius, --table-radius).

Descriptive Names

Color names are chosen to be semantically meaningful rather than literal color values, allowing for easier theme changes. For example:

• --color-primary: Represents the main brand color.
• --color-accent: Represents an accent color used for highlights.
• --color-text-primary: The main text color.
• --color-text-muted: A lighter text color for less emphasis.
• --color-surface: The background color for UI elements like cards or panels.
• --color-background: The overall page background color.

This approach ensures that the CSS variables are intuitive, maintainable, and easily adaptable for future theme customizations.

Per-page data & actions

Short reference of per-page APIs and primary actions used by templates and scripts.

• Scenarios (templates/ScenarioForm.html):

  • Data: GET /api/scenarios/
  • Actions: POST /api/scenarios/

• Parameters (templates/ParameterInput.html):

  • Data: GET /api/scenarios/, GET /api/parameters/
  • Actions: POST /api/parameters/

• Costs (templates/costs.html):

  • Data: GET /api/costs/capex, GET /api/costs/opex
  • Actions: POST /api/costs/capex, POST /api/costs/opex

• Consumption (templates/consumption.html):

  • Data: GET /api/consumption/
  • Actions: POST /api/consumption/

• Production (templates/production.html):

  • Data: GET /api/production/
  • Actions: POST /api/production/

• Equipment (templates/equipment.html):

  • Data: GET /api/equipment/
  • Actions: POST /api/equipment/

• Maintenance (templates/maintenance.html):

  • Data: GET /api/maintenance/ (pagination support)
  • Actions: POST /api/maintenance/, PUT /api/maintenance/{id}, DELETE /api/maintenance/{id}

• Simulations (templates/simulations.html):

  • Data: GET /api/scenarios/, GET /api/parameters/
  • Actions: POST /api/simulations/run

• Reporting (templates/reporting.html and templates/Dashboard.html):

  • Data: POST /api/reporting/summary (accepts arrays of { "result": float } objects)
  • Actions: Trigger summary refreshes and export/download actions.

Navigation Structure

The application uses a sidebar navigation menu organized into the following top-level categories:

• Dashboard: Main overview page.
• Overview: Sub-menu for core scenario inputs.
  • Parameters: Process parameters configuration.
  • Costs: Capital and operating costs.
  • Consumption: Resource consumption tracking.
  • Production: Production output settings.
  • Equipment: Equipment inventory (with Maintenance sub-item).
• Simulations: Monte Carlo simulation runs.
• Analytics: Reporting and analytics.
• Settings: Administrative settings (with Themes and Currency Management sub-items).

UI Template Audit (2025-10-20)

• Existing HTML templates: ScenarioForm.html, ParameterInput.html, and Dashboard.html (reporting summary view).
• Coverage gaps remain for costs, consumption, production, equipment, maintenance, and simulation workflows—no dedicated templates yet.
• Shared layout primitives (navigation/header/footer) are absent; current pages duplicate boilerplate markup.
• Dashboard currently covers reporting metrics but should be wired to a central / route once the shared layout lands.
• Next steps: introduce a base.html, refactor existing templates to extend it, and scaffold placeholder pages for the remaining features.