feat: Add application-level settings for CSS color management

- Introduced a new table `application_setting` to store configurable application options.
- Implemented functions to manage CSS color settings, including loading, updating, and reading environment overrides.
- Added a new settings view to render and manage theme colors.
- Updated UI to include a settings page with theme color management and environment overrides display.
- Enhanced CSS styles for the settings page and sidebar navigation.
- Created unit and end-to-end tests for the new settings functionality and CSS management.

static/css/main.css

@@ -117,6 +117,37 @@ body {
   gap: 0.5rem;
 }
 
+.sidebar-section {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.sidebar-section + .sidebar-section {
+  margin-top: 1.4rem;
+}
+
+.sidebar-section-label {
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: rgba(255, 255, 255, 0.52);
+  padding: 0 1rem;
+}
+
+.sidebar-section-links {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.sidebar-link-block {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+}
+
 .sidebar-link {
   display: inline-flex;
   align-items: center;
@@ -142,6 +173,39 @@ body {
   box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.25);
 }
 
+.sidebar-sublinks {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  padding-left: 1.75rem;
+}
+
+.sidebar-sublink {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  color: rgba(255, 255, 255, 0.74);
+  font-weight: 500;
+  font-size: 0.9rem;
+  text-decoration: none;
+  padding: 0.35rem 0.75rem;
+  border-radius: 8px;
+  transition: background 0.2s ease, color 0.2s ease, transform 0.2s ease;
+}
+
+.sidebar-sublink:hover,
+.sidebar-sublink:focus {
+  background: rgba(148, 197, 255, 0.18);
+  color: var(--color-text-invert);
+  transform: translateX(3px);
+}
+
+.sidebar-sublink.is-active {
+  background: rgba(148, 197, 255, 0.28);
+  color: var(--color-text-invert);
+  box-shadow: inset 0 0 0 1px rgba(255, 255, 255, 0.18);
+}
+
 .app-main {
   background-color: var(--color-background);
   display: flex;
@@ -185,6 +249,159 @@ body {
   align-items: center;
 }
 
+.page-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1.5rem;
+  margin-bottom: 2rem;
+}
+
+.page-subtitle {
+  margin-top: 0.35rem;
+  color: var(--color-text-muted);
+  font-size: 0.95rem;
+}
+
+.settings-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 1.5rem;
+  margin-bottom: 2rem;
+}
+
+.settings-card {
+  background: var(--color-surface);
+  border-radius: 12px;
+  padding: 1.5rem;
+  box-shadow: 0 4px 14px var(--color-panel-shadow);
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.settings-card h2 {
+  margin: 0;
+  font-size: 1.2rem;
+}
+
+.settings-card p {
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.settings-card-note {
+  font-size: 0.85rem;
+  color: var(--color-text-subtle);
+}
+
+.color-form-grid {
+  max-width: none;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+}
+
+.color-form-field {
+  background: var(--color-surface-alt);
+  border: 1px solid var(--color-border);
+  border-radius: 10px;
+  padding: var(--space-sm);
+  box-shadow: inset 0 1px 2px rgba(15, 23, 42, 0.08);
+  gap: var(--space-sm);
+}
+
+.color-form-field.is-env-override {
+  background: rgba(191, 248, 56, 0.12);
+  border-color: var(--color-accent);
+}
+
+.color-field-header {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--space-sm);
+  font-weight: 600;
+  color: var(--color-text-strong);
+  font-family: "Fira Code", "Consolas", "Courier New", monospace;
+  font-size: 0.85rem;
+}
+
+.color-field-default {
+  color: var(--color-text-muted);
+  font-weight: 500;
+}
+
+.color-field-helper {
+  font-size: 0.8rem;
+  color: var(--color-text-subtle);
+}
+
+.color-env-flag {
+  font-size: 0.78rem;
+  font-weight: 600;
+  color: var(--color-accent);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.color-input-row {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+.color-value-input {
+  font-family: "Fira Code", "Consolas", "Courier New", monospace;
+}
+
+.color-value-input[disabled] {
+  background-color: rgba(148, 197, 255, 0.16);
+  cursor: not-allowed;
+}
+
+.color-preview {
+  width: 32px;
+  height: 32px;
+  border-radius: 8px;
+  border: 1px solid var(--color-border-strong);
+  box-shadow: inset 0 0 0 1px rgba(15, 23, 42, 0.05);
+}
+
+.env-overrides-table table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.env-overrides-table th,
+.env-overrides-table td {
+  padding: 0.65rem 0.75rem;
+  text-align: left;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.env-overrides-table code {
+  font-family: "Fira Code", "Consolas", "Courier New", monospace;
+  font-size: 0.85rem;
+}
+
+.button-link {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: fit-content;
+  padding: 0.55rem 1.2rem;
+  border-radius: 999px;
+  font-weight: 600;
+  text-decoration: none;
+  background: var(--color-primary);
+  color: var(--color-text-invert);
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+.button-link:hover,
+.button-link:focus {
+  transform: translateY(-1px);
+  box-shadow: 0 8px 18px var(--color-panel-shadow);
+}
+
 .dashboard-metrics-grid {
   display: grid;
   grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));

static/js/settings.js

@@ -0,0 +1,200 @@
+(function () {
+  const dataScript = document.getElementById("theme-settings-data");
+  const form = document.getElementById("theme-settings-form");
+  const feedbackEl = document.getElementById("theme-settings-feedback");
+  const resetBtn = document.getElementById("theme-settings-reset");
+  const panel = document.getElementById("theme-settings");
+
+  if (!dataScript || !form || !feedbackEl || !panel) {
+    return;
+  }
+
+  const apiUrl = panel.getAttribute("data-api");
+  if (!apiUrl) {
+    return;
+  }
+
+  const parsed = JSON.parse(dataScript.textContent || "{}");
+  const currentValues = { ...(parsed.variables || {}) };
+  const defaultValues = parsed.defaults || {};
+  let envOverrides = { ...(parsed.envOverrides || {}) };
+
+  const previewElements = new Map();
+  const inputs = Array.from(form.querySelectorAll(".color-value-input"));
+
+  inputs.forEach((input) => {
+    const key = input.name;
+    const field = input.closest(".color-form-field");
+    const preview = field ? field.querySelector(".color-preview") : null;
+    if (preview) {
+      previewElements.set(input, preview);
+    }
+
+    if (Object.prototype.hasOwnProperty.call(envOverrides, key)) {
+      const overrideValue = envOverrides[key];
+      input.value = overrideValue;
+      input.disabled = true;
+      input.setAttribute("aria-disabled", "true");
+      input.dataset.envOverride = "true";
+      if (field) {
+        field.classList.add("is-env-override");
+      }
+      if (preview) {
+        preview.style.background = overrideValue;
+      }
+      return;
+    }
+
+    input.addEventListener("input", () => {
+      const previewEl = previewElements.get(input);
+      if (previewEl) {
+        previewEl.style.background = input.value || defaultValues[key] || "";
+      }
+    });
+  });
+
+  function setFeedback(message, type) {
+    feedbackEl.textContent = message;
+    feedbackEl.classList.remove("hidden", "success", "error");
+    if (type) {
+      feedbackEl.classList.add(type);
+    }
+  }
+
+  function clearFeedback() {
+    feedbackEl.textContent = "";
+    feedbackEl.classList.add("hidden");
+    feedbackEl.classList.remove("success", "error");
+  }
+
+  function updateRootVariables(values) {
+    if (!values) {
+      return;
+    }
+    const root = document.documentElement;
+    Object.entries(values).forEach(([key, value]) => {
+      if (typeof key === "string" && typeof value === "string") {
+        root.style.setProperty(key, value);
+      }
+    });
+  }
+
+  function resetTo(source) {
+    inputs.forEach((input) => {
+      const key = input.name;
+      if (input.disabled) {
+        const previewEl = previewElements.get(input);
+        const fallback = envOverrides[key] || currentValues[key];
+        if (previewEl && fallback) {
+          previewEl.style.background = fallback;
+        }
+        return;
+      }
+      if (Object.prototype.hasOwnProperty.call(source, key)) {
+        input.value = source[key];
+        const previewEl = previewElements.get(input);
+        if (previewEl) {
+          previewEl.style.background = source[key];
+        }
+      }
+    });
+  }
+
+  // Initialize previews to current values after page load.
+  resetTo(currentValues);
+
+  resetBtn?.addEventListener("click", () => {
+    resetTo(defaultValues);
+    clearFeedback();
+    setFeedback("Reverted to default values. Submit to save.", "success");
+  });
+
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    clearFeedback();
+
+    const payload = {};
+    inputs.forEach((input) => {
+      if (input.disabled) {
+        return;
+      }
+      payload[input.name] = input.value.trim();
+    });
+
+    try {
+      const response = await fetch(apiUrl, {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ variables: payload }),
+      });
+
+      if (!response.ok) {
+        let detail = "Unable to save theme settings.";
+        try {
+          const errorData = await response.json();
+          if (errorData?.detail) {
+            detail = Array.isArray(errorData.detail)
+              ? errorData.detail.map((item) => item.msg || item).join("; ")
+              : errorData.detail;
+          }
+        } catch (parseError) {
+          // Ignore JSON parse errors and use default detail message.
+        }
+        setFeedback(detail, "error");
+        return;
+      }
+
+      const data = await response.json();
+      const variables = data?.variables || {};
+      const responseOverrides = data?.env_overrides || {};
+
+      Object.assign(currentValues, variables);
+      envOverrides = { ...responseOverrides };
+
+      inputs.forEach((input) => {
+        const key = input.name;
+        const field = input.closest(".color-form-field");
+        const previewEl = previewElements.get(input);
+        const isOverride = Object.prototype.hasOwnProperty.call(
+          envOverrides,
+          key,
+        );
+
+        if (isOverride) {
+          const overrideValue = envOverrides[key];
+          input.value = overrideValue;
+          if (!input.disabled) {
+            input.disabled = true;
+            input.setAttribute("aria-disabled", "true");
+          }
+          if (field) {
+            field.classList.add("is-env-override");
+          }
+          if (previewEl) {
+            previewEl.style.background = overrideValue;
+          }
+        } else if (input.disabled) {
+          input.disabled = false;
+          input.removeAttribute("aria-disabled");
+          if (field) {
+            field.classList.remove("is-env-override");
+          }
+          if (
+            previewEl &&
+            Object.prototype.hasOwnProperty.call(variables, key)
+          ) {
+            previewEl.style.background = variables[key];
+          }
+        }
+      });
+
+      updateRootVariables(variables);
+      resetTo(variables);
+      setFeedback("Theme colors updated successfully.", "success");
+    } catch (error) {
+      setFeedback("Network error: unable to save settings.", "error");
+    }
+  });
+})();