common themeConfig.ts

# Dashboard Refactor

## Overview

This merge request performs a major cleanup and architectural refactor of the dashboard component system.

The primary goals were:

* Consolidate dashboard state handling
* Standardize component contracts
* Remove duplicated transaction aggregation logic
* Simplify theming
* Eliminate unnecessary wrapper/view layers
* Improve maintainability and type safety

---

# Major Changes

## Dashboard Architecture Refactor

### Consolidated State API

Introduced a centralized `DashboardStateSetters` interface:

```ts
export interface DashboardStateSetters {
  setSelectedPeriodId: (id: DashboardSelectedPeriodId) => void;
  setSelectedGroupKey: (groupKey: GroupKey | null) => void;
  toggleFlow: () => void;
  togglePeriodType: () => void;
  toggleComparison: () => void;
}
```

This removes scattered prop drilling and standardizes dashboard interaction handling.

---

### Introduced Shared `ComponentProps`

All dashboard widgets now consume a unified contract:

```ts
export interface ComponentProps extends DashboardSection {
  reportData: ReportData;

  state: DashboardState;
  stateSetters: DashboardStateSetters;
  isFetching: boolean;

  colorScheme: {
    primary: string;
    light: string;
    text: string;
  };
}
```

Benefits:

* Consistent widget APIs
* Reduced repetitive prop definitions
* Easier extensibility
* Cleaner component composition

---

### Removed `Dashboard.view.tsx`

The view/container split was removed.

Dashboard rendering now lives directly inside:

```ts
Dashboard.tsx
```

Benefits:

* Reduced indirection
* Easier navigation
* Lower cognitive overhead
* Simpler state flow

---

## Dashboard Config Cleanup

Removed legacy `style.size` configuration from dashboard sections.

Before:

```ts
style: {
  size: 12,
}
```

Now:

```ts
{
  id: "items",
  title: "Recent Transactions",
  component: LatestItems,
}
```

This simplifies section configuration and removes unnecessary abstraction.

---

# Shared Transaction Utilities

## Added `extractFilteredTransactions`

Created a reusable transaction extraction helper:

```ts
extractFilteredTransactions(
  reportData,
  selectedPeriodId,
  selectedGroupKey
)
```

This centralizes:

* Period resolution
* Group filtering
* Tag filtering
* Payee filtering

Previously duplicated across:

* LatestItems
* TopTags
* TopPayees

---

## Added `aggregateTransactions`

Created a reusable aggregation utility:

```ts
aggregateTransactions(
  transactions,
  keyExtractor,
  limit
)
```

Benefits:

* Removes repeated Map aggregation logic
* Standardizes sorting and totals
* Simplifies adapters significantly

---

# HistoryChart Refactor

## Split Models vs Props

Separated:

* data models
* component props
* view props

into dedicated files.

New:

```txt
HistoryChart.models.ts
HistoryChart.props.ts
```

Benefits:

* Cleaner typing boundaries
* Better maintainability
* Reduced coupling

---

## Migrated to Shared Dashboard State

HistoryChart now consumes:

```ts
state
stateSetters
```

instead of individual props.

This aligns it with the new dashboard architecture.

---

# LatestItems Refactor

## Simplified Component Contract

Removed duplicated props:

* flow
* header
* accentColor
* selectedPeriodId
* selectedGroupKey

Now inherited from shared `ComponentProps`.

---

## Added Auto Reset on Flow Change

```ts
React.useEffect(() => {
  setVisibleCount(5);
}, [flow]);
```

Improves UX when switching inflow/outflow views.

---

# ProgressCard Refactor

## Removed `ProgressCard.tsx`

Deleted unnecessary wrapper component.

Rendering logic now lives directly in:

```txt
ProgressCard.view.tsx
```

---

## Introduced `ProgressCard.props.ts`

Separated props into dedicated interfaces:

```ts
ProgressCardProps
ProgressCardViewProps
```

---

## Reworked Styling System

Removed dependency on:

```ts
colorTheme
```

Now fully driven by:

```ts
colorScheme
```

Benefits:

* Consistent dashboard-wide theming
* Better dark mode behavior
* Reduced MUI palette coupling

---

## Improved Visual Consistency

Updated:

* borders
* shadows
* progress bar styling
* dark mode surfaces
* selection state styling

to use standardized dashboard colors.

---

# TopTags & TopPayees Refactor

## Removed Duplicated Aggregation Logic

Both adapters now use:

```ts
extractFilteredTransactions()
aggregateTransactions()
```

instead of maintaining separate filtering/aggregation implementations.

Benefits:

* Less code duplication
* Consistent behavior
* Easier future maintenance

---

## Migrated to Shared Component Props

Both components now consume:

```ts
ComponentProps
```

via:

```ts
ProgressCardProps
```

This aligns all dashboard widgets under the same architecture.

---

# Theme System Cleanup

## Consolidated AppTheme

Moved to:

```txt
src/shared-theme/AppTheme.tsx
```

and removed unused duplicate implementations.

---

## Added Explicit Color Mode Context

Introduced:

```ts
ColorModeContext
```

with:

* `mode`
* `setMode`
* `toggleColorMode`

This provides a cleaner foundation for future theme controls.

---

## Simplified Theme Creation

Replaced older MUI experimental color scheme setup with:

```ts
getDesignTokens(mode)
```

Benefits:

* Easier to reason about
* Cleaner light/dark handling
* Less framework complexity

---

## Added Global CssBaseline

```tsx
<CssBaseline />
```

is now applied centrally inside `AppTheme`.

---

# Type Safety Improvements

## Removed Optional Fields Where Invalid

Several previously optional fields are now required:

```ts
title: string
background: string
text: string
isFetching: boolean
style.palette
```

Benefits:

* Stronger guarantees
* Fewer runtime fallbacks
* Simpler rendering logic

---

# Cleanup Summary

## Removed

* `Dashboard.view.tsx`
* `ProgressCard.tsx`
* legacy prop duplication
* repeated transaction extraction logic
* repeated aggregation logic
* unused style configuration
* legacy theme configuration complexity

---

## Added

* centralized dashboard state setters
* reusable transaction helpers
* reusable aggregation helper
* unified component props
* dedicated prop definition files
* explicit color mode context
* consolidated theme provider

---

# Result

The dashboard system is now:

* significantly more maintainable
* easier to extend
* more type-safe
* less repetitive
* more consistent across widgets
* cleaner in terms of state ownership
* simpler to theme and customize

Reviewed-on: #5
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

src/AppTheme.tsx

@@ -1,48 +0,0 @@
-import * as React from "react";
-import { ThemeProvider, createTheme } from "@mui/material/styles";
-import { getDesignTokens } from "./shared-theme/themePrimitives";
-import { inputsCustomizations } from "./shared-theme/customizations/inputs";
-import { dataDisplayCustomizations } from "./shared-theme/customizations/dataDisplay";
-import { feedbackCustomizations } from "./shared-theme/customizations/feedback";
-import { navigationCustomizations } from "./shared-theme/customizations/navigation";
-import { surfacesCustomizations } from "./shared-theme/customizations/surfaces";
-
-export const ColorModeContext = React.createContext({
-  toggleColorMode: () => {},
-  mode: "light" as "light" | "dark",
-});
-
-export default function AppTheme({ children }: { children: React.ReactNode }) {
-  const [mode, setMode] = React.useState<"light" | "dark">("light");
-
-  const colorMode = React.useMemo(
-    () => ({
-      toggleColorMode: () => {
-        setMode((prevMode) => (prevMode === "light" ? "dark" : "light"));
-      },
-      mode,
-    }),
-    [mode]
-  );
-
-  const theme = React.useMemo(
-    () =>
-      createTheme({
-        ...getDesignTokens(mode),
-        components: {
-          ...inputsCustomizations,
-          ...dataDisplayCustomizations,
-          ...feedbackCustomizations,
-          ...navigationCustomizations,
-          ...surfacesCustomizations,
-        },
-      }),
-    [mode]
-  );
-
-  return (
-    <ColorModeContext.Provider value={colorMode}>
-      <ThemeProvider theme={theme}>{children}</ThemeProvider>
-    </ColorModeContext.Provider>
-  );
-}

src/Dashboard.tsx

@@ -10,8 +10,14 @@ import {
   Button
 } from "@mui/material";
 
-import ConfigurableDashboard from "./components/Dashboard";
+import DashboardView from "./components/Dashboard";
-import { DashboardState } from "./components/Dashboard";
+
+import {
+  DashboardState,
+  DashboardStateSetters,
+  DashboardFlow,
+} from "./components/Dashboard";
+
 import { configuration } from "./dashboard-config";
 import {
   useReport,
@@ -19,7 +25,13 @@ import {
 } from "./features/report";
 
 export default function Dashboard() {
-  const [flow, setFlow] = React.useState<"outflows" | "inflows">("outflows");
+  const [state, setState] = React.useState<DashboardState>({
+    flow: "outflows",
+    periodType: "rolling",
+    selectedPeriodId: null,
+    selectedGroupKey: null,
+    comparison: false,
+  });
 
   const [appliedPayees, setAppliedPayees] = React.useState<string[]>([]);
   const [appliedTags, setAppliedTags] = React.useState<string[]>([]);
@@ -32,7 +44,7 @@ export default function Dashboard() {
 
   const report = useReport({
     periods: ["daily", "weekly", "monthly", "all"],
-    flow: flow,
+    flow: state.flow,
     payee: appliedPayees.length > 0 ? appliedPayees : undefined,
     tags: appliedTags.length > 0 ? appliedTags : undefined,
   });
@@ -69,14 +81,124 @@ export default function Dashboard() {
     }
   }, [report.data?.data]);
 
+  const toggleFlow =
+    React.useCallback(() => {
+      setState((prev) => ({
+        ...prev,
+
+        flow:
+          prev.flow ===
+          "outflows"
+            ? "inflows"
+            : "outflows",
+
+        selectedGroupKey:
+          null,
+
+        selectedPeriodId:
+          null,
+      }));
+    }, []);
+
+  const setFlow =
+    React.useCallback(
+      (
+        flow: DashboardFlow
+      ) => {
+        setState((prev) => ({
+          ...prev,
+
+          flow,
+
+          selectedGroupKey:
+            null,
+
+          selectedPeriodId:
+            null,
+        }));
+      },
+      []
+    );
+
+  const togglePeriodType =
+    React.useCallback(() => {
+      setState((prev) => ({
+        ...prev,
+
+        periodType:
+          prev.periodType ===
+          "rolling"
+            ? "calendar"
+            : "rolling",
+      }));
+    }, []);
+
+  const toggleComparison =
+    React.useCallback(() => {
+      setState((prev) => ({
+        ...prev,
+
+        comparison:
+          !prev.comparison,
+      }));
+    }, []);
+
+  const setSelectedPeriodId =
+    React.useCallback(
+      (
+        selectedPeriodId: DashboardState["selectedPeriodId"]
+      ) => {
+        setState((prev) => ({
+          ...prev,
+
+          selectedPeriodId,
+        }));
+      },
+      []
+    );
+
+  const setSelectedGroupKey =
+    React.useCallback(
+      (
+        selectedGroupKey: DashboardState["selectedGroupKey"]
+      ) => {
+        setState((prev) => ({
+          ...prev,
+
+          selectedGroupKey,
+        }));
+      },
+      []
+    );
+
+  const stateSetters: DashboardStateSetters =
+    React.useMemo(
+      () => ({
+        toggleFlow,
+
+        setFlow,
+
+        togglePeriodType,
+
+        toggleComparison,
+
+        setSelectedPeriodId,
+
+        setSelectedGroupKey,
+      }),
+      [
+        toggleFlow,
+        setFlow,
+        togglePeriodType,
+        toggleComparison,
+        setSelectedPeriodId,
+        setSelectedGroupKey,
+      ]
+    );
+
   const isLoading = report.isLoading;
   const error = report.error;
 
-  /** Callback for the ConfigurableDashboard's flow toggle */
-  const handleFlowChange = React.useCallback((newState: DashboardState) => {
-    setFlow(newState.flow);
-  }, []);
-
   if (isLoading && !report.data) {
     return (
       <Box sx={{ display: "flex", justifyContent: "center", alignItems: "center", height: "60vh" }}>
@@ -157,11 +279,12 @@ export default function Dashboard() {
           </Button>
         </Paper>
       </Container>
-      <ConfigurableDashboard
+      <DashboardView
         config={configuration}
         data={data}
+        state={state}
+        stateSetters={stateSetters}
         isFetching={report.isFetching}
-        onFlowChange={handleFlowChange}
       />
     </Box>
   );

src/Header.tsx

@@ -20,7 +20,7 @@ import DarkModeIcon from "@mui/icons-material/DarkMode";
 import LightModeIcon from "@mui/icons-material/LightMode";
 import { useNavigate } from "react-router-dom";
 import { useAuth } from "../react-auth";
-import { ColorModeContext } from "./AppTheme";
+import { ColorModeContext } from "./shared-theme/AppTheme";
 
 interface HeaderProps {
   routerMapping: {

src/Home.tsx

@@ -1,10 +1,12 @@
 import * as React from "react";
 import { Box, Typography, Button, Container, Stack } from "@mui/material";
+import { useTheme, alpha } from "@mui/material/styles";
 import { useNavigate } from "react-router-dom";
 import ArrowForwardIcon from "@mui/icons-material/ArrowForward";
 
 export default function Home() {
   const navigate = useNavigate();
+  const theme = useTheme();
 
   return (
     <Box
@@ -46,14 +48,13 @@ export default function Home() {
           sx={{
             p: { xs: 4, md: 8 },
             backdropFilter: "blur(20px)",
-            backgroundColor: (theme) => 
+            backgroundColor: (t) => alpha(t.palette.common.white, t.palette.mode === "dark" ? 0.04 : 0.6),
-               theme.palette.mode === "dark" ? "rgba(255, 255, 255, 0.03)" : "rgba(255, 255, 255, 0.6)",
             border: "1px solid",
             borderColor: "divider",
             borderRadius: 4,
-            boxShadow: (theme) =>
+            boxShadow: (t) =>
-              theme.palette.mode === "dark"
+              t.palette.mode === "dark"
-                ? "0 8px 32px 0 rgba(0, 0, 0, 0.37)"
+                ? "0 8px 32px 0 rgba(0, 0, 0, 0.5)"
                 : "0 8px 32px 0 rgba(31, 38, 135, 0.07)",
           }}
         >
@@ -94,7 +95,7 @@ export default function Home() {
                 transition: "transform 0.2s ease-in-out, box-shadow 0.2s",
                 "&:hover": {
                   transform: "translateY(-3px)",
-                  boxShadow: "0 8px 20px rgba(236,72,153,0.4)",
+                  boxShadow: (t) => `0 8px 20px ${alpha(t.palette.primary.main, 0.4)}`,
                 },
               }}
             >

src/components/Dashboard/Dashboard.models.ts

@@ -16,40 +16,46 @@ export interface DashboardState {
   comparison: boolean;
 }
 
+export interface DashboardStateSetters {
+  setSelectedPeriodId: (id: DashboardSelectedPeriodId) => void;
+  setSelectedGroupKey: (groupKey: GroupKey | null) => void;
+  toggleFlow: () => void;
+  togglePeriodType: () => void;
+  toggleComparison: () => void;
+}
+
 export interface DashboardSection {
   id: string;
-  title?: string;
+  title: string;
-  summary?: string;
   component: React.ComponentType<any>;
+  summary?: string;
   settings?: Record<string, any>;
-  isList?: boolean;
-  style?: {
-    size?: number;
-    [key: string]: any;
-  };
-}
-
-export interface ColorDefinition {
-  primary: string;
-  background?: string;
-  text?: string;
-}
-
-export interface ThemeAwarePalette {
-  light: ColorDefinition;
-  dark: ColorDefinition;
 }
 
 export interface DashboardConfig {
   sections: DashboardSection[];
-  style?: {
-    palette?: Record<DashboardFlow, ThemeAwarePalette>;
-  };
 }
 
-export interface DashboardProps {
+export interface DashboardViewProps {
   config: DashboardConfig;
   data: ReportData;
-  isFetching?: boolean;
+  state: DashboardState;
-  onFlowChange?: (state: DashboardState) => void;
+  stateSetters: DashboardStateSetters;
+  isFetching: boolean;
+}
+
+export interface ColorScheme {
+  primary: string;
+  surface: string;
+  text: string;
+}
+
+export interface ComponentProps extends DashboardSection {
+  reportData: ReportData;
+
+  state: DashboardState;
+  stateSetters: DashboardStateSetters;
+  isFetching: boolean;
+
+  colorScheme: ColorScheme;
 }

src/components/Dashboard/Dashboard.tsx

@@ -1,64 +0,0 @@
-import * as React from "react";
-import DashboardView from "./Dashboard.view";
-import { DashboardProps, DashboardState } from "./Dashboard.models";
-
-export default function Dashboard(props: DashboardProps) {
-  const [state, setState] = React.useState<DashboardState>({
-    flow: "outflows",
-    periodType: "rolling",
-    selectedPeriodId: null,
-    selectedGroupKey: null,
-    comparison: false,
-  });
-
-  const toggleFlow = (
-    event: React.MouseEvent<HTMLElement>,
-    newFlow: "outflows" | "inflows" | null
-  ) => {
-    if (newFlow === null) return;
-
-    setState(prev => {
-      if (prev.flow === newFlow) return prev;
-
-      const next = { ...prev, flow: newFlow };
-      props.onFlowChange?.(next);
-
-      return next;
-    });
-  };
-
-  const togglePeriodType = () => {
-    setState(prev => ({
-      ...prev,
-      periodType: prev.periodType === "rolling" ? "calendar" : "rolling",
-    }));
-  };
-
-  const toggleComparison = () => {
-    setState(prev => ({
-      ...prev,
-      comparison: !prev.comparison,
-    }));
-  };
-
-  const setSelectedPeriodId = (selectedPeriodId: typeof state.selectedPeriodId) => {
-    setState(prev => ({ ...prev, selectedPeriodId }));
-  };
-
-  const setSelectedGroupKey = (groupKey: typeof state.selectedGroupKey) => {
-    setState(prev => ({ ...prev, selectedGroupKey: groupKey }));
-  };
-
-  return (
-    <DashboardView
-      {...props}
-      state={state}
-      setState={setState}
-      toggleFlow={toggleFlow}
-      togglePeriodType={togglePeriodType}
-      toggleComparison={toggleComparison}
-      setSelectedPeriodId={setSelectedPeriodId}
-      setSelectedGroupKey={setSelectedGroupKey}
-    />
-  );
-}

src/components/Dashboard/Dashboard.view.tsx

@@ -3,90 +3,64 @@ import {
   Box,
   Container,
   Grid,
-  Typography,
   ToggleButton,
   ToggleButtonGroup,
   Button
 } from "@mui/material";
 import { useTheme, alpha } from "@mui/material/styles";
-import { GroupKey } from "../../features/report";
+import { DashboardViewProps } from "./Dashboard.models";
-import { DashboardProps, DashboardState } from "./Dashboard.models";
-
-interface ViewProps extends DashboardProps {
-  state: DashboardState;
-  setState: React.Dispatch<React.SetStateAction<DashboardState>>;
-  toggleFlow: (event: React.MouseEvent<HTMLElement>, newFlow: "outflows" | "inflows" | null) => void;
-  togglePeriodType: () => void;
-  setSelectedPeriodId: (id: string | null) => void;
-  setSelectedGroupKey: (groupKey: GroupKey | null) => void;
-  toggleComparison: () => void;
-}
 
 export default function DashboardView({
   config,
   data,
   state,
-  setState,
+  stateSetters,
-  toggleFlow,
+  isFetching,
-  togglePeriodType,
+}: DashboardViewProps) {
-  toggleComparison,
-  setSelectedPeriodId,
-  setSelectedGroupKey,
-}: ViewProps) {
   const theme = useTheme();
-  const themeMode = theme.palette.mode;
-  const { flow, periodType, comparison, selectedPeriodId, selectedGroupKey } = state;
 
-  // Resolve colors with fallbacks
+  const {
-  const colors = React.useMemo(() => {
+    flow,
-    const palette = config.style?.palette?.[flow];
+    selectedGroupKey,
-    const modeColors = palette ? palette[themeMode] : null;
+  } = state;
 
-    if (modeColors) {
+  const colorScheme = flow === "outflows" ? theme.palette.flows.outflows : theme.palette.flows.inflows;
-      return {
-        primary: modeColors.primary,
-        light: modeColors.background || alpha(modeColors.primary, 0.1),
-        text: modeColors.text || (themeMode === 'light' ? theme.palette.text.primary : '#fff')
-      };
-    }
-
-    // Fallback to standard theme colors
-    const themeColor = flow === 'outflows' ? theme.palette.error : theme.palette.success;
-    return {
-      primary: themeColor.main,
-      light: alpha(themeColor.main, themeMode === 'light' ? 0.08 : 0.15),
-      text: themeColor.main
-    };
-  }, [config.style?.palette, flow, themeMode, theme.palette]);
 
   return (
     <Container
       sx={{
         mt: 4,
         mb: 4,
-        background: `linear-gradient(180deg, ${colors.light} 0%, transparent 100%)`,
+        background: `linear-gradient(180deg, ${alpha(colorScheme.primary, theme.palette.mode === "dark" ? 0.06 : 0.04)} 0%, transparent 100%)`,
         borderRadius: 4,
         p: 2,
-        transition: 'background 0.3s ease'
+        transition: "background 0.3s ease",
+      }}
+    >
+      <Box
+        sx={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          mb: 3,
         }}
       >
-      <Box sx={{ display: "flex", flexDirection: "column", alignItems: "center", mb: 3 }}>
         <ToggleButtonGroup
           value={flow}
           exclusive
-          onChange={toggleFlow}
+          onChange={stateSetters.toggleFlow}
           sx={{
             borderRadius: 3,
             overflow: "hidden",
             "& .MuiToggleButton-root": {
               px: 3,
               textTransform: "none",
-              color: "text.secondary"
+              color: "text.secondary",
             },
             "&.Mui-selected": {
-              bgcolor: colors.primary,
+              bgcolor: colorScheme.primary,
               color: "white",
-              borderColor: colors.primary
+              borderColor: colorScheme.primary,
             },
           }}
         >
@@ -98,7 +72,7 @@ export default function DashboardView({
           <Button
             size="small"
             sx={{ mt: 1, textTransform: "none" }}
-            onClick={() => setSelectedGroupKey(null)}
+            onClick={() => stateSetters.setSelectedGroupKey(null)}
           >
             Clear Drill-down
           </Button>
@@ -110,29 +84,17 @@ export default function DashboardView({
           const Component = section.component;
 
           return (
-            <Grid key={section.id} size={section.style?.size || 12 as any}>
+            <Grid key={section.id} size={12}>
               <Component
-                {...section.settings}
+                {...section}
-                header={section.title}
+
-                summary={section.summary}
                 reportData={data}
-                title={section.title}
-                accentColor={colors.primary}
-                colorScheme={colors}
 
-                // State management
+                state={state}
-                flow={flow}
+                stateSetters={stateSetters}
+                isFetching={isFetching}
 
-                periodType={periodType}
+                colorScheme={colorScheme}
-                comparison={comparison}
-                selectedPeriodId={selectedPeriodId}
-                selectedGroupKey={selectedGroupKey}
-
-                togglePeriodType={togglePeriodType}
-                toggleComparison={toggleComparison}
-                setSelectedPeriodId={setSelectedPeriodId}
-                setSelectedGroupKey={setSelectedGroupKey}
-                isFetching={arguments[0].isFetching}
               />
             </Grid>
           );

src/components/Dashboard/index.ts

@@ -1,2 +1,2 @@
-export { default } from "./Dashboard";
+export { default } from "./Dashboard.view";
 export * from "./Dashboard.models";

src/components/HistoryChart/HistoryChart.models.ts

@@ -1,10 +1,3 @@
-import {
-  DashboardFlow,
-  DashboardPeriodType,
-  DashboardSelectedPeriodId
-} from "../Dashboard";
-import { ReportData } from "../../features/report";
-
 export interface _ChartDataPoint {
   id: string;
   label: string;
@@ -15,28 +8,3 @@ export interface _ChartDataPoint {
 export interface ChartDataPoint extends _ChartDataPoint {
   compare?: _ChartDataPoint;
 }
-
-export interface HistoryChartProps {
-  header: string;
-  summary?: string;
-  tabs: string[];
-
-  reportData: ReportData;
-
-  colorScheme: {
-    primary: string;
-    light: string;
-    text: string;
-  };
-
-  flow: DashboardFlow;
-  periodType: DashboardPeriodType;
-  selectedPeriodId: DashboardSelectedPeriodId;
-  comparison: boolean;
-
-  togglePeriodType: () => void;
-  setSelectedPeriodId: (id: string | null) => void;
-  toggleComparison: () => void;
-
-  isFetching?: boolean;
-}

src/components/HistoryChart/HistoryChart.props.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import { ComponentProps } from "../Dashboard";
+import { ChartDataPoint } from "./HistoryChart.models";
+
+export interface HistoryChartProps extends ComponentProps {
+  settings: {
+    tabs: string[];
+  };
+}
+
+export interface HistoryChartViewProps extends HistoryChartProps {
+  activeTab: string;
+  setActiveTab: (v: string) => void;
+  currentData: ChartDataPoint[];
+  visibleData: ChartDataPoint[];
+  maxAmount: number;
+  visibleCount: number;
+  startIndex: number;
+  setStartIndex: React.Dispatch<React.SetStateAction<number>>;
+  activeDataKey: string;
+}

src/components/HistoryChart/HistoryChart.tsx

@@ -1,18 +1,23 @@
 import * as React from "react";
-import { HistoryChartProps } from "./HistoryChart.models";
 import HistoryChartView from "./HistoryChart.view";
 import { buildChartData, tabToKey } from "./HistoryChart.adapter";
+import { HistoryChartProps } from "./HistoryChart.props";
+
 
 export default function HistoryChart(props: HistoryChartProps) {
   const {
-    tabs,
+    settings,
     reportData,
-    flow,
+    state,
-    comparison,
+    stateSetters,
-    selectedPeriodId,
+
-    setSelectedPeriodId
+    isFetching,
   } = props;
 
+  const { flow, comparison, selectedPeriodId } = state;
+  const { setSelectedPeriodId } = stateSetters;
+  const { tabs } = settings;
+
   const [activeTab, setActiveTab] = React.useState<string>(tabs[0] || "");
   const [startIndex, setStartIndex] = React.useState(0);
 

src/components/HistoryChart/HistoryChart.view.tsx

@@ -11,39 +11,21 @@ import IconButton from "@mui/material/IconButton";
 import ChevronLeftIcon from "@mui/icons-material/ChevronLeft";
 import ChevronRightIcon from "@mui/icons-material/ChevronRight";
 import {
-  ChartDataPoint,
+  HistoryChartViewProps,
-  HistoryChartProps,
+} from "./HistoryChart.props";
-} from "./HistoryChart.models";
 import { formatDisplay } from "./HistoryChart.utils";
 
-interface ViewProps extends HistoryChartProps {
+export default function HistoryChartView({
-  activeTab: string;
+  title,
-  setActiveTab: (v: string) => void;
-  currentData: ChartDataPoint[];
-  visibleData: ChartDataPoint[];
-  maxAmount: number;
-  visibleCount: number;
-  startIndex: number;
-  setStartIndex: React.Dispatch<React.SetStateAction<number>>;
-  activeDataKey: string;
-}
-
-export default function HistoryChartView(props: ViewProps) {
-  const {
-    header,
   summary,
-    tabs,
+  settings,
+
+  state,
+  stateSetters,
+  isFetching,
+
   colorScheme,
 
-    flow,
-    periodType,
-    selectedPeriodId,
-    comparison,
-
-    togglePeriodType,
-    setSelectedPeriodId,
-    toggleComparison,
-
   activeTab,
   setActiveTab,
   currentData,
@@ -53,7 +35,10 @@ export default function HistoryChartView(props: ViewProps) {
   startIndex,
   setStartIndex,
   activeDataKey,
-  } = props;
+}: HistoryChartViewProps) {
+
+  const { flow, periodType, selectedPeriodId, comparison } = state;
+  const { togglePeriodType, setSelectedPeriodId, toggleComparison } = stateSetters;
 
   const theme = useTheme();
   const isDark = theme.palette.mode === "dark";
@@ -91,14 +76,14 @@ export default function HistoryChartView(props: ViewProps) {
         boxShadow: "none",
         border: "1px solid",
         borderColor: "divider",
-        bgcolor: isDark ? "background.paper" : colorScheme.light,
+        bgcolor: isDark ? "background.paper" : colorScheme.surface,
-        opacity: props.isFetching ? 0.6 : 1,
+        opacity: isFetching ? 0.6 : 1,
         transition: "opacity 0.3s ease",
-        pointerEvents: props.isFetching ? "none" : "auto",
+        pointerEvents: isFetching ? "none" : "auto",
       }}
     >
       <Typography variant="h6" fontWeight={700} gutterBottom>
-        {header}
+        {title}
       </Typography>
 
       {summary && (
@@ -108,7 +93,7 @@ export default function HistoryChartView(props: ViewProps) {
       )}
 
       <ToggleButtonGroup value={activeTab} exclusive onChange={handleTabChange} fullWidth sx={{ mb: 4 }}>
-        {tabs.map((tab) => (
+        {settings.tabs.map((tab) => (
           <ToggleButton key={tab} value={tab}>
             {tab}
           </ToggleButton>

src/components/LatestItems/LatestItems.adapter.ts

@@ -1,67 +1,19 @@
-import { ReportData, Transaction, GroupKey } from "../../features/report";
+import { ReportData, GroupKey } from "../../features/report";
 import {
-  mergeBucketPeriods,
-  periodIdToKey,
   formatCurrency,
-  filterBuckets,
+  extractFilteredTransactions,
 } from "../report.helpers";
 import { LatestItem } from "./LatestItems.models";
 
-// ─── Transaction extraction ─────────────────────────────────
-
-function extractTransactions(
-  reportData: ReportData,
-  selectedPeriodId: string | null,
-  selectedGroupKey: GroupKey | null,
-): Transaction[] {
-  // 1. Get raw transactions
-  let rawTxns: Transaction[] = [];
-
-  if (selectedPeriodId) {
-    const key = periodIdToKey(selectedPeriodId);
-    const periods = mergeBucketPeriods(reportData.buckets, key);
-    const selected = periods.find((p) => p.id === selectedPeriodId);
-    rawTxns = selected?.metric.transactions || [];
-  } else {
-    const periods = mergeBucketPeriods(reportData.buckets, "all");
-    if (periods.length > 0) {
-      rawTxns = periods[0].metric.transactions || [];
-    }
-  }
-
-  // 2. Filter by group key
-  if (selectedGroupKey) {
-    rawTxns = rawTxns.filter(txn => {
-      let match = true;
-      if (selectedGroupKey.tags && selectedGroupKey.tags.length > 0) {
-        if (!txn.tags) match = false;
-        else {
-          const txnTags = txn.tags.map(t => typeof t === "string" ? t : t.name);
-          if (!selectedGroupKey.tags.every(selectedTag => txnTags.includes(selectedTag))) match = false;
-        }
-      }
-      if (match && selectedGroupKey.payee && selectedGroupKey.payee.length > 0) {
-        if (!txn.payee || !txn.payee.name) match = false;
-        else {
-          if (!selectedGroupKey.payee.includes(txn.payee.name)) match = false;
-        }
-      }
-      return match;
-    });
-  }
-
-  return rawTxns;
-}
-
 // ─── Main adapter ────────────────────────────────────────────
 
 export function buildLatestItems(
   reportData: ReportData,
-  selectedPeriodId: string | null,
+  selectedPeriodId: string | null | undefined,
-  selectedGroupKey: GroupKey | null,
+  selectedGroupKey: GroupKey | null | undefined,
   flow: "outflows" | "inflows"
 ): LatestItem[] {
-  const txns = extractTransactions(reportData, selectedPeriodId, selectedGroupKey);
+  const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
 
   return txns
     .sort(

src/components/LatestItems/LatestItems.models.ts

@@ -5,12 +5,3 @@ export interface LatestItem {
   amount: string;
   timeAgo: string;
 }
-
-export interface LatestItemsViewProps {
-  items: LatestItem[];
-  header: string;
-  accentColor: string;
-  canExpand: boolean;
-  onExpand: () => void;
-  isFetching?: boolean;
-}

src/components/LatestItems/LatestItems.props.ts

@@ -0,0 +1,10 @@
+import { ComponentProps } from "../Dashboard";
+import { LatestItem } from "./LatestItems.models";
+
+export interface LatestItemsProps extends ComponentProps {}
+
+export interface LatestItemsViewProps extends LatestItemsProps {
+  items: LatestItem[];
+  canExpand: boolean;
+  onExpand: () => void;
+}

src/components/LatestItems/LatestItems.tsx

@@ -1,29 +1,24 @@
 import * as React from "react";
-import { ReportData, GroupKey } from "../../features/report";
 import { buildLatestItems } from "./LatestItems.adapter";
 import LatestItemsView from "./LatestItems.view";
+import { LatestItemsProps } from "./LatestItems.props";
 
-type Props = {
+export default function LatestItems(props: LatestItemsProps) {
-  reportData: ReportData;
+  const {
-  flow: "outflows" | "inflows";
-  header: string;
-  selectedPeriodId: string | null;
-  selectedGroupKey?: GroupKey | null;
-  accentColor: string;
-  isFetching?: boolean;
-};
-
-export default function LatestItems({
     reportData,
-  flow,
+    state,
-  header,
+    stateSetters,
-  selectedPeriodId,
-  selectedGroupKey = null,
-  accentColor,
     isFetching,
-}: Props) {
+  } = props;
+
+  const { flow, selectedPeriodId, selectedGroupKey } = state;
   const [visibleCount, setVisibleCount] = React.useState(5);
 
+  // Reset count when flow changes to start clean
+  React.useEffect(() => {
+    setVisibleCount(5);
+  }, [flow]);
+
   const allItems = React.useMemo(() => {
     return buildLatestItems(reportData, selectedPeriodId, selectedGroupKey, flow);
   }, [reportData, selectedPeriodId, selectedGroupKey, flow]);
@@ -36,11 +31,9 @@ export default function LatestItems({
 
   return (
     <LatestItemsView
+      {...props}
       items={visibleItems}
-      header={header}
-      accentColor={accentColor}
       canExpand={canExpand}
-      isFetching={isFetching}
       onExpand={() => setVisibleCount((prev) => prev + 5)}
     />
   );

src/components/LatestItems/LatestItems.view.tsx

@@ -9,22 +9,25 @@ import {
   Box,
   IconButton,
 } from "@mui/material";
+import { alpha } from "@mui/material/styles";
 import ExpandMoreIcon from "@mui/icons-material/ExpandMore";
-import { LatestItemsViewProps } from "./LatestItems.models";
+import { LatestItemsViewProps } from "./LatestItems.props";
 
 export default function LatestItemsView({
   items,
-  header,
+  title,
-  accentColor,
   canExpand,
   onExpand,
   isFetching,
+  colorScheme,
 }: LatestItemsViewProps) {
+  const accentColor = colorScheme?.primary || "";
+
   return (
     <Box sx={{ width: "100%", bgcolor: "background.paper", borderRadius: 4, p: 2, opacity: isFetching ? 0.6 : 1, transition: "opacity 0.3s ease", pointerEvents: isFetching ? "none" : "auto" }}>
       <Box sx={{ mb: 2, px: 2 }}>
         <Typography variant="h6" fontWeight="bold">
-          {header}
+          {title}
         </Typography>
       </Box>
 
@@ -44,7 +47,7 @@ export default function LatestItemsView({
               <Avatar
                 variant="rounded"
                 sx={{
-                  bgcolor: `${accentColor}22`,
+                  bgcolor: alpha(accentColor, 0.13),
                   width: 48,
                   height: 48,
                   borderRadius: 3,

src/components/ProgressCard/ProgressCard.models.ts

@@ -1,11 +0,0 @@
-export interface ProgressCardProps {
-  header: string;
-  summary?: string;
-  progressAmount: number;
-  totalAmount: number;
-  colorTheme?: "primary" | "secondary" | "error" | "info" | "success" | "warning";
-  compact?: boolean;
-  selected?: boolean;
-  onClick?: () => void;
-  isFetching?: boolean;
-}

src/components/ProgressCard/ProgressCard.props.ts

@@ -0,0 +1,14 @@
+import { ComponentProps } from "../Dashboard";
+
+export interface ProgressCardProps extends ComponentProps {
+  settings: {
+    compact: boolean;
+  };
+}
+
+export interface ProgressCardViewProps extends ProgressCardProps {
+  progressAmount: number;
+  totalAmount: number;
+  selected: boolean;
+  onClick: () => void;
+}

src/components/ProgressCard/ProgressCard.tsx

@@ -1,25 +0,0 @@
-import * as React from "react";
-import ProgressCardView from "./ProgressCard.view";
-import { ProgressCardProps } from "./ProgressCard.models";
-import { getPercentage, formatCurrency } from "../report.helpers";
-
-export default function ProgressCard(props: ProgressCardProps) {
-  const { progressAmount, totalAmount, compact = false } = props;
-
-  const percentage = getPercentage(progressAmount, totalAmount);
-  
-  const formattedProgress = formatCurrency(progressAmount);
-  const formattedTotal = formatCurrency(totalAmount);
-
-  return (
-    <ProgressCardView
-      {...props}
-      percentage={percentage}
-      formattedProgress={formattedProgress}
-      formattedTotal={formattedTotal}
-      compact={compact}
-      selected={props.selected}
-      onClick={props.onClick}
-    />
-  );
-}

src/components/ProgressCard/ProgressCard.view.tsx

@@ -8,93 +8,79 @@ import {
   linearProgressClasses
 } from "@mui/material";
 import { useTheme, alpha } from "@mui/material/styles";
-import { ProgressCardProps } from "./ProgressCard.models";
+import { getPercentage, formatCurrency } from "../report.helpers";
-
+import { ProgressCardViewProps } from "./ProgressCard.props";
-interface ViewProps extends ProgressCardProps {
-  percentage: number;
-  formattedProgress: string;
-  formattedTotal: string;
-  selected?: boolean;
-  onClick?: () => void;
-}
 
 export default function ProgressCardView({
-  header,
+  title,
-  colorTheme = "info",
+  settings,
-  percentage,
+
-  formattedProgress,
+  isFetching,
-  formattedTotal,
+
-  compact = false,
+  colorScheme,
+
+  progressAmount,
+  totalAmount,
   selected,
   onClick,
-}: ViewProps) {
+}: ProgressCardViewProps) {
   const theme = useTheme();
-  const isDark = theme.palette.mode === "dark";
+
+  const percentage = getPercentage(progressAmount, totalAmount);
+  const formattedProgress = formatCurrency(progressAmount);
+  const formattedTotal = formatCurrency(totalAmount);
 
   return (
     <Paper
-      elevation={compact ? 2 : 4}
+      elevation={settings.compact ? 2 : 4}
       onClick={onClick}
       sx={{
         width: "100%",
-        p: compact ? { xs: 2.5, md: 3 } : { xs: 3, md: 4 },
+        p: settings.compact ? { xs: 2.5, md: 3 } : { xs: 3, md: 4 },
-        borderRadius: compact ? 3 : 4,
+        borderRadius: settings.compact ? 3 : 4,
-        cursor: onClick ? "pointer" : "default",
         transform: selected ? "scale(1.02)" : "scale(1)",
         transition: "transform 0.2s ease, box-shadow 0.2s ease",
-        background: (theme) => {
+        bgcolor: colorScheme.surface,
-          const baseColor = theme.palette[colorTheme]?.main || theme.palette.primary.main;
+        color: colorScheme.text,
-          const lightColor = theme.palette[colorTheme]?.light || theme.palette.primary.light;
-          return isDark
-            ? `linear-gradient(135deg, ${alpha(baseColor, 0.9)} 0%, ${alpha(baseColor, 0.3)} 100%)`
-            : `linear-gradient(135deg, ${baseColor} 0%, ${lightColor} 100%)`;
-        },
-        color: "#fff",
         display: "flex",
         flexDirection: "column",
-        alignItems: compact ? "flex-start" : "center",
+        alignItems: settings.compact ? "flex-start" : "center",
         justifyContent: "center",
         position: "relative",
         overflow: "hidden",
         border: selected
-          ? `2px solid #fff`
+          ? `2px solid ${colorScheme.primary}`
-          : isDark ? "1px solid rgba(255,255,255,0.1)" : "none",
+          : "1px solid",
-        boxShadow: (theme) => {
+        borderColor: selected ? colorScheme.primary : "divider",
-          const baseShadow = `0 ${compact ? 6 : 12}px ${compact ? 12 : 24}px -10px ${
+        boxShadow: "none",
-            isDark
+        opacity: isFetching ? 0.6 : 1,
-              ? "rgba(0,0,0,0.5)"
+        pointerEvents: isFetching ? "none" : "auto",
-              : theme.palette[colorTheme]?.main || theme.palette.primary.main
-          }`;
-          return selected 
-            ? `${baseShadow}, 0 0 0 2px ${theme.palette.background.paper}, 0 0 0 4px ${theme.palette[colorTheme]?.main || theme.palette.primary.main}` 
-            : baseShadow;
-        },
-        opacity: arguments[0].isFetching ? 0.6 : 1,
-        pointerEvents: arguments[0].isFetching ? "none" : "auto",
       }}
     >
       <Typography
-        variant={compact ? "body2" : "subtitle1"} 
+        variant={settings.compact ? "body2" : "subtitle1"}
         fontWeight={700}
         sx={{
           opacity: 0.95,
-          mb: compact ? 1.5 : 2, 
+          mb: settings.compact ? 1.5 : 2,
-          width: '100%', 
+          width: "100%",
-          overflow: 'hidden', 
+          overflow: "hidden",
-          textOverflow: 'ellipsis', 
+          textOverflow: "ellipsis",
-          whiteSpace: 'nowrap',
+          whiteSpace: "nowrap",
           letterSpacing: 0.5,
-          textShadow: isDark ? '0 1px 2px rgba(0,0,0,0.3)' : 'none'
         }}
       >
-        {header}
+        {title}
       </Typography>
 
-      <Box sx={{ mb: compact ? 2 : 3, width: '100%' }}>
+      <Box sx={{ mb: settings.compact ? 2 : 3, width: "100%" }}>
         <Typography
-          variant={compact ? "h5" : "h3"}
+          variant={settings.compact ? "h5" : "h3"}
           fontWeight={900}
-          sx={{ mb: 0.5, lineHeight: 1.2, textShadow: isDark ? '0 2px 4px rgba(0,0,0,0.3)' : 'none' }}
+          sx={{
+            mb: 0.5,
+            lineHeight: 1.2,
+          }}
         >
           {formattedProgress}
         </Typography>
@@ -102,38 +88,38 @@ export default function ProgressCardView({
         <Divider
           sx={{
             my: 1,
-            borderColor: "rgba(255,255,255,0.25)",
+            borderColor: "divider",
             width: "100%",
           }}
         />
 
         <Typography
-          variant={compact ? "caption" : "body2"}
+          variant={settings.compact ? "caption" : "body2"}
           sx={{
             opacity: 0.85,
             fontWeight: 500,
             display: "block",
-            color: "rgba(255,255,255,0.9)"
+            color: alpha(colorScheme.text, 0.85),
           }}
         >
           of {formattedTotal}
         </Typography>
       </Box>
 
-      <Box sx={{ width: "100%", mt: 'auto' }}>
+      <Box sx={{ width: "100%", mt: "auto" }}>
         <LinearProgress
           variant="determinate"
           value={percentage}
           sx={{
-            height: compact ? 6 : 10,
+            height: settings.compact ? 6 : 10,
             borderRadius: 5,
             [`&.${linearProgressClasses.colorPrimary}`]: {
-              backgroundColor: "rgba(0, 0, 0, 0.25)",
+              backgroundColor: alpha(theme.palette.divider, 0.5),
             },
             [`& .${linearProgressClasses.bar}`]: {
               borderRadius: 5,
-              backgroundColor: "#fff",
+              backgroundColor: colorScheme.primary,
-              boxShadow: '0 0 8px rgba(255,255,255,0.4)'
+              boxShadow: `0 0 8px ${alpha(colorScheme.primary, 0.4)}`,
             },
           }}
         />

src/components/ProgressCard/TopPayees.adapter.ts

@@ -1,5 +1,8 @@
-import { mergeBucketPeriods, periodIdToKey } from "../report.helpers";
 import { GroupKey, ReportData } from "../../features/report";
+import {
+  extractFilteredTransactions,
+  aggregateTransactions,
+} from "../report.helpers";
 
 export interface PayeeItem {
   name: string;
@@ -12,54 +15,17 @@ export function extractTopPayees(
   selectedPeriodId?: string | null,
   selectedGroupKey?: GroupKey | null
 ): { items: PayeeItem[]; total: number } {
-  const payeeMap = new Map<string, number>();
+  const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
 
-  let targetPeriods = [];
+  const { items, total } = aggregateTransactions(txns, (txn) => {
-
-  if (selectedPeriodId) {
-    const key = periodIdToKey(selectedPeriodId);
-    const periods = mergeBucketPeriods(reportData.buckets, key);
-    const selected = periods.find((p) => p.id === selectedPeriodId);
-    if (selected) {
-      targetPeriods.push(selected);
-    }
-  } else {
-    // If no specific period is selected, aggregate over the "all" period bucket
-    targetPeriods = mergeBucketPeriods(reportData.buckets, "all");
-  }
-
-  for (const p of targetPeriods) {
-    let txns = p.metric.transactions || [];
-    
-    if (selectedGroupKey?.tags && selectedGroupKey.tags.length > 0) {
-      txns = txns.filter(txn => {
-        if (!txn.tags) return false;
-        const txnTags = txn.tags.map(t => typeof t === "string" ? t : t.name);
-        return selectedGroupKey.tags!.every(selectedTag => txnTags.includes(selectedTag));
-      });
-    }
-
-    for (const txn of txns) {
     if (txn.payee && txn.payee.name) {
-        const current = payeeMap.get(txn.payee.name) || 0;
+      return [txn.payee.name];
-        payeeMap.set(txn.payee.name, current + txn.amount);
     }
-    }
+    return [];
-  }
+  });
-
-  let items: PayeeItem[] = [];
-  let total = 0;
-
-  for (const [name, amount] of payeeMap.entries()) {
-    items.push({ name, amount });
-    total += amount;
-  }
-
-  // Sort descending by amount
-  items.sort((a, b) => b.amount - a.amount);
 
   return {
-    items: items.slice(0, 4), // Top 4
+    items,
     total,
   };
 }

src/components/ProgressCard/TopPayees.tsx

@@ -1,30 +1,22 @@
 import * as React from "react";
 import { Box, Paper, Typography } from "@mui/material";
-import { ReportData, GroupKey } from "../../features/report";
+import ProgressCardView from "./ProgressCard.view";
-import ProgressCard from "./ProgressCard";
 import { extractTopPayees } from "./TopPayees.adapter";
+import { ProgressCardProps } from "./ProgressCard.props";
 
-type Props = {
+export default function TopPayees(props: ProgressCardProps) {
-  reportData: ReportData;
+  const {
-  flow: "outflows" | "inflows";
+    title,
-  header: string;
-  selectedPeriodId?: string | null;
-  selectedGroupKey?: GroupKey | null;
-  setSelectedGroupKey?: (key: GroupKey | null) => void;
-  compact?: boolean;
-  isFetching?: boolean;
-};
 
-export default function TopPayees({
     reportData,
-  flow,
+    state,
-  header,
+    stateSetters,
-  selectedPeriodId,
+
-  selectedGroupKey,
-  setSelectedGroupKey,
-  compact = true,
     isFetching,
-}: Props) {
+  } = props
+  const { flow, selectedPeriodId, selectedGroupKey } = state;
+  const { setSelectedGroupKey } = stateSetters;
+
   const { items, total } = React.useMemo(() => {
     return extractTopPayees(reportData, flow, selectedPeriodId, selectedGroupKey);
   }, [reportData, flow, selectedPeriodId, selectedGroupKey]);
@@ -45,7 +37,7 @@ export default function TopPayees({
       }}
     >
       <Typography variant="h6" fontWeight={700} gutterBottom>
-        {header}
+        {title}
       </Typography>
 
       <Box
@@ -60,17 +52,15 @@ export default function TopPayees({
         }}
       >
         {items.map((item) => {
-          const isSelected = selectedGroupKey?.payee?.includes(item.name);
+          const isSelected = !!selectedGroupKey?.payee?.includes(item.name);
           return (
-            <ProgressCard
+            <ProgressCardView
+              {...props}
               key={item.name}
-              header={item.name}
+              title={item.name}
               progressAmount={item.amount}
               totalAmount={total}
-              compact={compact}
-              colorTheme={flow === "outflows" ? "error" : "success"}
               selected={isSelected}
-              isFetching={isFetching}
               onClick={() => {
                 if (setSelectedGroupKey) {
                   let newKey = selectedGroupKey ? { ...selectedGroupKey } : {};

src/components/ProgressCard/TopTags.adapter.ts

@@ -1,11 +1,9 @@
-import { ReportData } from "../../features/report";
+import { ReportData, GroupKey } from "../../features/report";
 import {
-  mergeBucketPeriods,
+  extractFilteredTransactions,
-  periodIdToKey,
+  aggregateTransactions,
 } from "../report.helpers";
 
-import { GroupKey } from "../../features/report";
-
 export interface TagItem {
   tag: string;
   amount: number;
@@ -17,55 +15,17 @@ export function extractTopTags(
   selectedPeriodId?: string | null,
   selectedGroupKey?: GroupKey | null
 ): { items: TagItem[]; total: number } {
-  const tagMap = new Map<string, number>();
+  const txns = extractFilteredTransactions(reportData, selectedPeriodId, selectedGroupKey);
 
-  let periodKey: ReturnType<typeof periodIdToKey> = "all";
+  const { items, total } = aggregateTransactions(txns, (txn) => {
-  if (selectedPeriodId) {
-    periodKey = periodIdToKey(selectedPeriodId);
-  }
-
-  const periods = mergeBucketPeriods(reportData.buckets, periodKey);
-
-  let period = periods[0];
-  if (selectedPeriodId) {
-    period = periods.find(p => p.id === selectedPeriodId) || period;
-  } else if (periods.length > 0) {
-    period = periods.reduce((latest, p) =>
-      new Date(p.start).getTime() > new Date(latest.start).getTime()
-        ? p
-        : latest
-    );
-  }
-
-  if (period && period.metric && period.metric.transactions) {
-    let txns = period.metric.transactions;
-    if (selectedGroupKey?.payee && selectedGroupKey.payee.length > 0) {
-      txns = txns.filter(txn => 
-        txn.payee?.name && selectedGroupKey.payee!.includes(txn.payee.name)
-      );
-    }
-
-    for (const txn of txns) {
     if (txn.tags && txn.tags.length > 0) {
-        for (const tagObj of txn.tags) {
+      return txn.tags.map((t) => (typeof t === "string" ? t : t.name));
-          const tagName = typeof tagObj === "string" ? tagObj : tagObj.name;
-          tagMap.set(tagName, (tagMap.get(tagName) || 0) + txn.amount);
-        }
-      } else {
-        tagMap.set("Untagged", (tagMap.get("Untagged") || 0) + txn.amount);
-      }
-    }
     }
+    return ["Untagged"];
+  });
 
-  const arr = Array.from(tagMap.entries()).map(([tag, amount]) => ({
+  return {
-    tag,
+    items: items.map((item) => ({ tag: item.name, amount: item.amount })),
-    amount,
+    total,
-  }));
+  };
-
-  arr.sort((a, b) => b.amount - a.amount);
-
-  const top = arr.slice(0, 4);
-  const total = top.reduce((sum, t) => sum + t.amount, 0);
-
-  return { items: top, total };
 }

src/components/ProgressCard/TopTags.tsx

@@ -1,30 +1,22 @@
 import * as React from "react";
 import { Box, Paper, Typography } from "@mui/material";
-import { ReportData, GroupKey } from "../../features/report";
+import ProgressCardView from "./ProgressCard.view";
-import ProgressCard from "./ProgressCard";
 import { extractTopTags } from "./TopTags.adapter";
+import { ProgressCardProps } from "./ProgressCard.props";
 
-type Props = {
+export default function TopTags(props: ProgressCardProps) {
-  reportData: ReportData;
+  const {
-  flow: "outflows" | "inflows";
+    title,
-  header: string;
-  selectedPeriodId?: string | null;
-  selectedGroupKey?: GroupKey | null;
-  setSelectedGroupKey?: (key: GroupKey | null) => void;
-  compact?: boolean;
-  isFetching?: boolean;
-};
 
-export default function TopTags({
     reportData,
-  flow,
+    state,
-  header,
+    stateSetters,
-  selectedPeriodId,
+
-  selectedGroupKey,
-  setSelectedGroupKey,
-  compact = true,
     isFetching,
-}: Props) {
+  } = props
+  const { flow, selectedPeriodId, selectedGroupKey } = state;
+  const { setSelectedGroupKey } = stateSetters;
+
   const { items, total } = React.useMemo(() => {
     return extractTopTags(reportData, flow, selectedPeriodId, selectedGroupKey);
   }, [reportData, flow, selectedPeriodId, selectedGroupKey]);
@@ -45,7 +37,7 @@ export default function TopTags({
       }}
     >
       <Typography variant="h6" fontWeight={700} gutterBottom>
-        {header}
+        {title}
       </Typography>
 
       <Box
@@ -60,17 +52,15 @@ export default function TopTags({
         }}
       >
         {items.map((item) => {
-          const isSelected = selectedGroupKey?.tags?.includes(item.tag);
+          const isSelected = !!selectedGroupKey?.tags?.includes(item.tag);
           return (
-            <ProgressCard
+            <ProgressCardView
+              {...props}
               key={item.tag}
-              header={item.tag}
+              title={item.tag}
               progressAmount={item.amount}
               totalAmount={total}
-              compact={compact}
-              colorTheme={flow === "outflows" ? "error" : "success"}
               selected={isSelected}
-              isFetching={isFetching}
               onClick={() => {
                 if (setSelectedGroupKey) {
                   let newKey = selectedGroupKey ? { ...selectedGroupKey } : {};

src/components/ProgressCard/index.ts

@@ -1,2 +1,2 @@
-export { default } from "./ProgressCard";
+export { default } from "./ProgressCard.view";
-export * from "./ProgressCard.models";
+export * from "./ProgressCard.props";

src/components/report.helpers.ts

@@ -3,6 +3,8 @@ import {
   ReportBucket,
   GroupKey,
   PeriodType,
+  ReportData,
+  Transaction,
 } from "../features/report";
 
 // ─── Types ────────────────────────────────────────────────────
@@ -140,3 +142,89 @@ export function filterBuckets(
   if (!selectedGroupKey) return buckets;
   return buckets.filter((b) => matchesGroupKey(b, selectedGroupKey));
 }
+
+export function extractFilteredTransactions(
+  reportData: ReportData,
+  selectedPeriodId: string | null | undefined,
+  selectedGroupKey: GroupKey | null | undefined
+): Transaction[] {
+  let txns: Transaction[] = [];
+
+  if (selectedPeriodId) {
+    const key = periodIdToKey(selectedPeriodId);
+    const periods = mergeBucketPeriods(reportData.buckets, key);
+    const selected = periods.find((p) => p.id === selectedPeriodId);
+    txns = selected?.metric.transactions || [];
+  } else {
+    const periods = mergeBucketPeriods(reportData.buckets, "all");
+    if (periods.length > 0) {
+      const period = periods.reduce((latest, p) =>
+        new Date(p.start).getTime() > new Date(latest.start).getTime()
+          ? p
+          : latest
+      , periods[0]);
+      txns = period?.metric.transactions || [];
+    }
+  }
+
+  if (selectedGroupKey) {
+    txns = txns.filter((txn) => {
+      let match = true;
+      if (selectedGroupKey.tags && selectedGroupKey.tags.length > 0) {
+        if (!txn.tags) {
+          match = false;
+        } else {
+          const txnTags = txn.tags.map((t: any) =>
+            typeof t === "string" ? t : t.name
+          );
+          if (
+            !selectedGroupKey.tags.every((selectedTag) =>
+              txnTags.includes(selectedTag)
+            )
+          ) {
+            match = false;
+          }
+        }
+      }
+      if (match && selectedGroupKey.payee && selectedGroupKey.payee.length > 0) {
+        if (!txn.payee || !txn.payee.name) {
+          match = false;
+        } else {
+          if (!selectedGroupKey.payee.includes(txn.payee.name)) {
+            match = false;
+          }
+        }
+      }
+      return match;
+    });
+  }
+
+  return txns;
+}
+
+export function aggregateTransactions(
+  transactions: Transaction[],
+  keyExtractor: (txn: Transaction) => string[],
+  limit = 4
+): { items: { name: string; amount: number }[]; total: number } {
+  const map = new Map<string, number>();
+
+  for (const txn of transactions) {
+    const keys = keyExtractor(txn);
+    for (const key of keys) {
+      map.set(key, (map.get(key) || 0) + txn.amount);
+    }
+  }
+
+  const items = Array.from(map.entries()).map(([name, amount]) => ({
+    name,
+    amount,
+  }));
+
+  items.sort((a, b) => b.amount - a.amount);
+
+  const top = items.slice(0, limit);
+  const total = top.reduce((sum, item) => sum + item.amount, 0);
+
+  return { items: top, total };
+}

src/dashboard-config.ts

@@ -14,9 +14,6 @@ export const configuration: DashboardConfig = {
       settings: {
         tabs: ["Weekly", "Monthly"],
       },
-      style: {
-        size: 12,
-      },
     },
     {
       id: "top-categories",
@@ -25,9 +22,6 @@ export const configuration: DashboardConfig = {
       settings: {
         compact: true,
       },
-      style: {
-        size: 12,
-      },
     },
     {
       id: "top-payees",
@@ -36,45 +30,11 @@ export const configuration: DashboardConfig = {
       settings: {
         compact: true,
       },
-      style: {
-        size: 12,
-      },
     },
     {
       id: "items",
       title: 'Recent Transactions',
       component: LatestItems,
-      style: {
-        size: 12,
-      },
     },
   ],
-  style: {
-    palette: {
-      outflows: {
-        light: {
-          primary: "#d32f2f",
-          background: "#fdecea",
-          text: "#b71c1c"
-        },
-        dark: {
-          primary: "#f44336",
-          background: "rgba(244, 67, 54, 0.15)",
-          text: "#ffcdd2"
-        }
-      },
-      inflows: {
-        light: {
-          primary: "#2e7d32",
-          background: "#e8f5e9",
-          text: "#1b5e20"
-        },
-        dark: {
-          primary: "#4caf50",
-          background: "rgba(76, 175, 80, 0.15)",
-          text: "#c8e6c9"
-        }
-      }
-    }
-  }
 };

src/main.jsx

@@ -19,7 +19,7 @@ import process from 'process';
 import { AuthProvider } from "../react-auth";
 import Header from './Header';
 import Footer from './Footer';
-import AppTheme from './AppTheme';
+import AppTheme from './shared-theme/AppTheme';
 
 window.Buffer = Buffer;
 window.process = process;

src/shared-theme/AppTheme.tsx

@@ -1,53 +1,103 @@
-import * as React from 'react';
+import * as React from "react";
-import { ThemeProvider, createTheme } from '@mui/material/styles';
+import {
-import type { ThemeOptions } from '@mui/material/styles';
+  ThemeProvider,
-import { inputsCustomizations } from './customizations/inputs';
+  createTheme,
-import { dataDisplayCustomizations } from './customizations/dataDisplay';
+  CssBaseline,
-import { feedbackCustomizations } from './customizations/feedback';
+  Box,
-import { navigationCustomizations } from './customizations/navigation';
+} from "@mui/material";
-import { surfacesCustomizations } from './customizations/surfaces';
-import { colorSchemes, typography, shadows, shape } from './themePrimitives';
 
-interface AppThemeProps {
+import { getDesignTokens } from "./themePrimitives";
+import { getSemanticColors } from "./themeConfig";
+
+import { inputsCustomizations } from "./customizations/inputs";
+import { dataDisplayCustomizations } from "./customizations/dataDisplay";
+import { feedbackCustomizations } from "./customizations/feedback";
+import { navigationCustomizations } from "./customizations/navigation";
+import { surfacesCustomizations } from "./customizations/surfaces";
+
+export type ColorMode = "light" | "dark";
+
+type ColorModeContextValue = {
+  mode: ColorMode;
+  setMode: (mode: ColorMode) => void;
+  toggleColorMode: () => void;
+};
+
+export const ColorModeContext =
+  React.createContext<ColorModeContextValue>({
+    mode: "light",
+    setMode: () => {},
+    toggleColorMode: () => {},
+  });
+
+type AppThemeProps = {
   children: React.ReactNode;
-  /**
+  defaultMode?: ColorMode;
-   * This is for the docs site. You can ignore it or remove it.
+};
-   */
+
-  disableCustomTheme?: boolean;
+export default function AppTheme({
-  themeComponents?: ThemeOptions['components'];
+  children,
-}
+  defaultMode = "light",
+}: AppThemeProps) {
+  const [mode, setMode] =
+    React.useState<ColorMode>(defaultMode);
+
+  const toggleColorMode = React.useCallback(() => {
+    setMode((prev) =>
+      prev === "light" ? "dark" : "light"
+    );
+  }, []);
+
+  const contextValue = React.useMemo(
+    () => ({
+      mode,
+      setMode,
+      toggleColorMode,
+    }),
+    [mode, toggleColorMode]
+  );
+
+  const semantic = React.useMemo(
+    () => getSemanticColors(mode),
+    [mode]
+  );
+
+  const theme = React.useMemo(
+    () =>
+      createTheme({
+        ...getDesignTokens(mode),
+        semantic,
 
-export default function AppTheme(props: AppThemeProps) {
-  const { children, disableCustomTheme, themeComponents } = props;
-  const theme = React.useMemo(() => {
-    return disableCustomTheme
-      ? {}
-      : createTheme({
-          // For more details about CSS variables configuration, see https://mui.com/material-ui/customization/css-theme-variables/configuration/
-          cssVariables: {
-            colorSchemeSelector: 'data-mui-color-scheme',
-            cssVarPrefix: 'template',
-          },
-          colorSchemes, // Recently added in v6 for building light & dark mode app, see https://mui.com/material-ui/customization/palette/#color-schemes
-          typography,
-          shadows,
-          shape,
         components: {
           ...inputsCustomizations,
           ...dataDisplayCustomizations,
           ...feedbackCustomizations,
           ...navigationCustomizations,
           ...surfacesCustomizations,
-            ...themeComponents,
         },
-        });
+      }),
-  }, [disableCustomTheme, themeComponents]);
+    [mode, semantic]
-  if (disableCustomTheme) {
+  );
-    return <React.Fragment>{children}</React.Fragment>;
+
-  }
   return (
-    <ThemeProvider theme={theme} disableTransitionOnChange>
+    <ColorModeContext.Provider value={contextValue}>
+      <ThemeProvider theme={theme}>
+        <CssBaseline />
+        <Box
+          sx={{
+            "--bg-page": semantic.surface.page,
+            "--bg-card": semantic.surface.card,
+            "--bg-elevated": semantic.surface.elevated,
+            "--border-default": semantic.border.default,
+            "--border-subtle": semantic.border.subtle,
+            "--text-primary": semantic.text.primary,
+            "--text-secondary": semantic.text.secondary,
+            "--text-muted": semantic.text.muted,
+          }}
+        >
           {children}
+        </Box>
       </ThemeProvider>
+    </ColorModeContext.Provider>
   );
 }

src/shared-theme/ColorModeIconDropdown.tsx

@@ -1,89 +0,0 @@
-import * as React from 'react';
-import DarkModeIcon from '@mui/icons-material/DarkModeRounded';
-import LightModeIcon from '@mui/icons-material/LightModeRounded';
-import Box from '@mui/material/Box';
-import IconButton, { IconButtonOwnProps } from '@mui/material/IconButton';
-import Menu from '@mui/material/Menu';
-import MenuItem from '@mui/material/MenuItem';
-import { useColorScheme } from '@mui/material/styles';
-
-export default function ColorModeIconDropdown(props: IconButtonOwnProps) {
-  const { mode, systemMode, setMode } = useColorScheme();
-  const [anchorEl, setAnchorEl] = React.useState<null | HTMLElement>(null);
-  const open = Boolean(anchorEl);
-  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
-    setAnchorEl(event.currentTarget);
-  };
-  const handleClose = () => {
-    setAnchorEl(null);
-  };
-  const handleMode = (targetMode: 'system' | 'light' | 'dark') => () => {
-    setMode(targetMode);
-    handleClose();
-  };
-  if (!mode) {
-    return (
-      <Box
-        data-screenshot="toggle-mode"
-        sx={(theme) => ({
-          verticalAlign: 'bottom',
-          display: 'inline-flex',
-          width: '2.25rem',
-          height: '2.25rem',
-          borderRadius: (theme.vars || theme).shape.borderRadius,
-          border: '1px solid',
-          borderColor: (theme.vars || theme).palette.divider,
-        })}
-      />
-    );
-  }
-  const resolvedMode = (systemMode || mode) as 'light' | 'dark';
-  const icon = {
-    light: <LightModeIcon />,
-    dark: <DarkModeIcon />,
-  }[resolvedMode];
-  return (
-    <React.Fragment>
-      <IconButton
-        data-screenshot="toggle-mode"
-        onClick={handleClick}
-        disableRipple
-        size="small"
-        aria-controls={open ? 'color-scheme-menu' : undefined}
-        aria-haspopup="true"
-        aria-expanded={open ? 'true' : undefined}
-        {...props}
-      >
-        {icon}
-      </IconButton>
-      <Menu
-        anchorEl={anchorEl}
-        id="account-menu"
-        open={open}
-        onClose={handleClose}
-        onClick={handleClose}
-        slotProps={{
-          paper: {
-            variant: 'outlined',
-            elevation: 0,
-            sx: {
-              my: '4px',
-            },
-          },
-        }}
-        transformOrigin={{ horizontal: 'right', vertical: 'top' }}
-        anchorOrigin={{ horizontal: 'right', vertical: 'bottom' }}
-      >
-        <MenuItem selected={mode === 'system'} onClick={handleMode('system')}>
-          System
-        </MenuItem>
-        <MenuItem selected={mode === 'light'} onClick={handleMode('light')}>
-          Light
-        </MenuItem>
-        <MenuItem selected={mode === 'dark'} onClick={handleMode('dark')}>
-          Dark
-        </MenuItem>
-      </Menu>
-    </React.Fragment>
-  );
-}

src/shared-theme/ColorModeSelect.tsx

@@ -1,28 +0,0 @@
-import * as React from 'react';
-import { useColorScheme } from '@mui/material/styles';
-import MenuItem from '@mui/material/MenuItem';
-import Select, { SelectProps } from '@mui/material/Select';
-
-export default function ColorModeSelect(props: SelectProps) {
-  const { mode, setMode } = useColorScheme();
-  if (!mode) {
-    return null;
-  }
-  return (
-    <Select
-      value={mode}
-      onChange={(event) =>
-        setMode(event.target.value as 'system' | 'light' | 'dark')
-      }
-      SelectDisplayProps={{
-        // @ts-ignore
-        'data-screenshot': 'toggle-mode',
-      }}
-      {...props}
-    >
-      <MenuItem value="system">System</MenuItem>
-      <MenuItem value="light">Light</MenuItem>
-      <MenuItem value="dark">Dark</MenuItem>
-    </Select>
-  );
-}

src/shared-theme/customizations/feedback.tsx

@@ -14,8 +14,8 @@ export const feedbackCustomizations: Components<Theme> = {
           color: orange[500],
         },
         ...theme.applyStyles('dark', {
-          backgroundColor: `${alpha(orange[900], 0.5)}`,
+          backgroundColor: alpha(orange[900], 0.35),
-          border: `1px solid ${alpha(orange[800], 0.5)}`,
+          border: `1px solid ${alpha(orange[800], 0.3)}`,
         }),
       }),
     },

src/shared-theme/customizations/inputs.tsx

@@ -125,15 +125,15 @@ export const inputsCustomizations: Components<Theme> = {
                 backgroundColor: gray[200],
               },
               ...theme.applyStyles('dark', {
-                backgroundColor: gray[800],
+                backgroundColor: 'hsla(0, 0%, 100%, 0.06)',
-                borderColor: gray[700],
+                borderColor: (theme.vars || theme).palette.divider,
 
                 '&:hover': {
-                  backgroundColor: gray[900],
+                  backgroundColor: 'hsla(0, 0%, 100%, 0.1)',
-                  borderColor: gray[600],
+                  borderColor: 'hsla(0, 0%, 100%, 0.15)',
                 },
                 '&:active': {
-                  backgroundColor: gray[900],
+                  backgroundColor: 'hsla(0, 0%, 100%, 0.1)',
                 },
               }),
             },
@@ -183,12 +183,12 @@ export const inputsCustomizations: Components<Theme> = {
                 backgroundColor: gray[200],
               },
               ...theme.applyStyles('dark', {
-                color: gray[50],
+                color: 'hsl(0, 0%, 92%)',
                 '&:hover': {
-                  backgroundColor: gray[700],
+                  backgroundColor: 'hsla(0, 0%, 100%, 0.08)',
                 },
                 '&:active': {
-                  backgroundColor: alpha(gray[700], 0.7),
+                  backgroundColor: 'hsla(0, 0%, 100%, 0.12)',
                 },
               }),
             },
@@ -241,14 +241,14 @@ export const inputsCustomizations: Components<Theme> = {
           backgroundColor: gray[200],
         },
         ...theme.applyStyles('dark', {
-          backgroundColor: gray[800],
+          backgroundColor: 'hsla(0, 0%, 100%, 0.06)',
-          borderColor: gray[700],
+          borderColor: (theme.vars || theme).palette.divider,
           '&:hover': {
-            backgroundColor: gray[900],
+            backgroundColor: 'hsla(0, 0%, 100%, 0.1)',
-            borderColor: gray[600],
+            borderColor: 'hsla(0, 0%, 100%, 0.15)',
           },
           '&:active': {
-            backgroundColor: gray[900],
+            backgroundColor: 'hsla(0, 0%, 100%, 0.1)',
           },
         }),
         variants: [
@@ -288,7 +288,7 @@ export const inputsCustomizations: Components<Theme> = {
           [`& .${toggleButtonGroupClasses.selected}`]: {
             color: '#fff',
           },
-          boxShadow: `0 4px 16px ${alpha(brand[700], 0.5)}`,
+          boxShadow: `0 2px 8px ${alpha(brand[700], 0.3)}`,
         }),
       }),
     },
@@ -302,7 +302,7 @@ export const inputsCustomizations: Components<Theme> = {
         fontWeight: 500,
         ...theme.applyStyles('dark', {
           color: gray[400],
-          boxShadow: '0 4px 16px rgba(0, 0, 0, 0.5)',
+          boxShadow: '0 2px 8px rgba(0, 0, 0, 0.25)',
           [`&.${toggleButtonClasses.selected}`]: {
             color: brand[300],
           },

src/shared-theme/customizations/navigation.tsx

@@ -49,9 +49,8 @@ export const navigationCustomizations: Components<Theme> = {
           },
         },
         ...theme.applyStyles('dark', {
-          background: gray[900],
+          background: (theme.vars || theme).palette.background.paper,
-          boxShadow:
+          boxShadow: '0 4px 16px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.3)',
-            'hsla(220, 30%, 5%, 0.7) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.8) 0px 8px 16px -5px',
         }),
       }),
     },
@@ -84,17 +83,17 @@ export const navigationCustomizations: Components<Theme> = {
 
         ...theme.applyStyles('dark', {
           borderRadius: (theme.vars || theme).shape.borderRadius,
-          borderColor: gray[700],
+          borderColor: (theme.vars || theme).palette.divider,
           backgroundColor: (theme.vars || theme).palette.background.paper,
-          boxShadow: `inset 0 1px 0 1px ${alpha(gray[700], 0.15)}, inset 0 -1px 0 1px hsla(220, 0%, 0%, 0.7)`,
+          boxShadow: 'inset 0 1px 0 hsla(0, 0%, 100%, 0.05)',
           '&:hover': {
-            borderColor: alpha(gray[700], 0.7),
+            borderColor: 'hsla(0, 0%, 100%, 0.15)',
             backgroundColor: (theme.vars || theme).palette.background.paper,
             boxShadow: 'none',
           },
           [`&.${selectClasses.focused}`]: {
             outlineOffset: 0,
-            borderColor: gray[900],
+            borderColor: 'hsl(210, 55%, 55%)',
           },
           '&:before, &:after': {
             display: 'none',
@@ -108,7 +107,7 @@ export const navigationCustomizations: Components<Theme> = {
           display: 'flex',
           alignItems: 'center',
           '&:focus-visible': {
-            backgroundColor: gray[900],
+            backgroundColor: (theme.vars || theme).palette.background.default,
           },
         }),
       }),
@@ -151,6 +150,7 @@ export const navigationCustomizations: Components<Theme> = {
     styleOverrides: {
       paper: ({ theme }) => ({
         backgroundColor: (theme.vars || theme).palette.background.default,
+        borderRight: `1px solid ${(theme.vars || theme).palette.divider}`,
       }),
     },
   },
@@ -204,8 +204,8 @@ export const navigationCustomizations: Components<Theme> = {
         ...theme.applyStyles('dark', {
           ':hover': {
             color: (theme.vars || theme).palette.text.primary,
-            backgroundColor: gray[800],
+            backgroundColor: alpha((theme.vars || theme).palette.common.white, 0.08),
-            borderColor: gray[700],
+            borderColor: (theme.vars || theme).palette.divider,
           },
           [`&.${tabClasses.selected}`]: {
             color: '#fff',

src/shared-theme/customizations/surfaces.ts

@@ -40,7 +40,7 @@ export const surfacesCustomizations: Components<Theme> = {
         '&:hover': { backgroundColor: gray[50] },
         '&:focus-visible': { backgroundColor: 'transparent' },
         ...theme.applyStyles('dark', {
-          '&:hover': { backgroundColor: gray[800] },
+          '&:hover': { backgroundColor: alpha(theme.palette.common.white, 0.06) },
         }),
       }),
     },
@@ -67,7 +67,7 @@ export const surfacesCustomizations: Components<Theme> = {
           border: `1px solid ${(theme.vars || theme).palette.divider}`,
           boxShadow: 'none',
           ...theme.applyStyles('dark', {
-            backgroundColor: gray[800],
+            backgroundColor: (theme.vars || theme).palette.background.paper,
           }),
           variants: [
             {
@@ -79,7 +79,7 @@ export const surfacesCustomizations: Components<Theme> = {
                 boxShadow: 'none',
                 background: 'hsl(0, 0%, 100%)',
                 ...theme.applyStyles('dark', {
-                  background: alpha(gray[900], 0.4),
+                  background: alpha((theme.vars || theme).palette.background.paper, 0.6),
                 }),
               },
             },

src/shared-theme/themeConfig.ts

@@ -0,0 +1,72 @@
+import { gray } from "./themePrimitives";
+import { alpha } from "@mui/material/styles";
+
+declare module "@mui/material/styles" {
+  interface Theme {
+    semantic: SemanticColors;
+  }
+  interface ThemeOptions {
+    semantic?: SemanticColors;
+  }
+}
+
+export type SemanticColorMode = "light" | "dark";
+
+export interface SemanticColors {
+  surface: {
+    page: string;
+    card: string;
+    elevated: string;
+  };
+  border: {
+    default: string;
+    subtle: string;
+  };
+  text: {
+    primary: string;
+    secondary: string;
+    muted: string;
+  };
+}
+
+const darkBg = 'hsl(0, 0%, 9%)';
+const darkPaper = 'hsl(0, 0%, 14%)';
+const darkElevated = 'hsl(0, 0%, 19%)';
+
+export function getSemanticColors(mode: SemanticColorMode): SemanticColors {
+  if (mode === "dark") {
+    return {
+      surface: {
+        page: darkBg,
+        card: darkPaper,
+        elevated: darkElevated,
+      },
+      border: {
+        default: 'hsla(0, 0%, 100%, 0.08)',
+        subtle: 'hsla(0, 0%, 100%, 0.04)',
+      },
+      text: {
+        primary: 'hsl(0, 0%, 92%)',
+        secondary: 'hsl(0, 0%, 60%)',
+        muted: 'hsl(0, 0%, 45%)',
+      },
+    };
+  }
+
+  return {
+    surface: {
+      page: "hsl(0, 0%, 99%)",
+      card: "hsl(220, 35%, 97%)",
+      elevated: gray[100],
+    },
+    border: {
+      default: alpha(gray[300], 0.4),
+      subtle: alpha(gray[200], 0.3),
+    },
+    text: {
+      primary: gray[800],
+      secondary: gray[600],
+      muted: gray[500],
+    },
+  };
+}

src/shared-theme/themePrimitives.ts

@@ -23,6 +23,10 @@ declare module '@mui/material/styles' {
 
   interface Palette {
     baseShadow: string;
+    flows: {
+      outflows: { primary: string; surface: string; text: string };
+      inflows: { primary: string; surface: string; text: string };
+    };
   }
 }
 
@@ -52,7 +56,9 @@ export const gray = {
   500: 'hsl(220, 20%, 42%)',
   600: 'hsl(220, 20%, 35%)',
   700: 'hsl(220, 20%, 25%)',
+  750: 'hsl(220, 20%, 18%)',
   800: 'hsl(220, 30%, 6%)',
+  850: 'hsl(220, 22%, 11%)',
   900: 'hsl(220, 35%, 3%)',
 };
 
@@ -95,10 +101,14 @@ export const red = {
   900: 'hsl(0, 93%, 6%)',
 };
 
+const darkBg = 'hsl(0, 0%, 9%)';
+const darkPaper = 'hsl(0, 0%, 14%)';
+const darkElevated = 'hsl(0, 0%, 19%)';
+
 export const getDesignTokens = (mode: PaletteMode) => {
   customShadows[1] =
     mode === 'dark'
-      ? 'hsla(220, 30%, 5%, 0.7) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.8) 0px 8px 16px -5px'
+      ? '0 4px 16px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.3)'
       : 'hsla(220, 30%, 5%, 0.07) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.07) 0px 8px 16px -5px';
 
   return {
@@ -111,9 +121,9 @@ export const getDesignTokens = (mode: PaletteMode) => {
         contrastText: brand[50],
         ...(mode === 'dark' && {
           contrastText: brand[50],
-          light: brand[300],
+          light: 'hsl(210, 50%, 65%)',
-          main: brand[400],
+          main: 'hsl(210, 55%, 55%)',
-          dark: brand[700],
+          dark: 'hsl(210, 50%, 35%)',
         }),
       },
       info: {
@@ -122,10 +132,10 @@ export const getDesignTokens = (mode: PaletteMode) => {
         dark: brand[600],
         contrastText: gray[50],
         ...(mode === 'dark' && {
-          contrastText: brand[300],
+          contrastText: 'hsl(210, 30%, 80%)',
-          light: brand[500],
+          light: 'hsl(210, 40%, 50%)',
-          main: brand[700],
+          main: 'hsl(210, 35%, 40%)',
-          dark: brand[900],
+          dark: 'hsl(210, 30%, 25%)',
         }),
       },
       warning: {
@@ -133,9 +143,9 @@ export const getDesignTokens = (mode: PaletteMode) => {
         main: orange[400],
         dark: orange[800],
         ...(mode === 'dark' && {
-          light: orange[400],
+          light: 'hsl(45, 60%, 55%)',
-          main: orange[500],
+          main: 'hsl(45, 55%, 45%)',
-          dark: orange[700],
+          dark: 'hsl(45, 50%, 30%)',
         }),
       },
       error: {
@@ -143,9 +153,9 @@ export const getDesignTokens = (mode: PaletteMode) => {
         main: red[400],
         dark: red[800],
         ...(mode === 'dark' && {
-          light: red[400],
+          light: 'hsl(0, 55%, 60%)',
-          main: red[500],
+          main: 'hsl(0, 55%, 50%)',
-          dark: red[700],
+          dark: 'hsl(0, 50%, 35%)',
         }),
       },
       success: {
@@ -153,34 +163,46 @@ export const getDesignTokens = (mode: PaletteMode) => {
         main: green[400],
         dark: green[800],
         ...(mode === 'dark' && {
-          light: green[400],
+          light: 'hsl(120, 40%, 55%)',
-          main: green[500],
+          main: 'hsl(120, 40%, 45%)',
-          dark: green[700],
+          dark: 'hsl(120, 35%, 30%)',
         }),
       },
       grey: {
         ...gray,
       },
-      divider: mode === 'dark' ? alpha(gray[700], 0.6) : alpha(gray[300], 0.4),
+      divider: mode === 'dark' ? 'hsla(0, 0%, 100%, 0.08)' : alpha(gray[300], 0.4),
       background: {
         default: 'hsl(0, 0%, 99%)',
         paper: 'hsl(220, 35%, 97%)',
-        ...(mode === 'dark' && { default: gray[900], paper: 'hsl(220, 30%, 7%)' }),
+        ...(mode === 'dark' && { default: darkBg, paper: darkPaper }),
       },
       text: {
         primary: gray[800],
         secondary: gray[600],
         warning: orange[400],
-        ...(mode === 'dark' && { primary: 'hsl(0, 0%, 100%)', secondary: gray[400] }),
+        ...(mode === 'dark' && { primary: 'hsl(0, 0%, 92%)', secondary: 'hsl(0, 0%, 60%)' }),
       },
       action: {
         hover: alpha(gray[200], 0.2),
         selected: `${alpha(gray[200], 0.3)}`,
         ...(mode === 'dark' && {
-          hover: alpha(gray[600], 0.2),
+          hover: 'hsla(0, 0%, 100%, 0.06)',
-          selected: alpha(gray[600], 0.3),
+          selected: 'hsla(0, 0%, 100%, 0.1)',
         }),
       },
+      flows: {
+        outflows: {
+          primary: mode === 'dark' ? 'hsl(0, 55%, 60%)' : '#d32f2f',
+          surface: mode === 'dark' ? 'hsla(0, 35%, 25%, 0.6)' : '#fdecea',
+          text: mode === 'dark' ? 'hsl(0, 60%, 80%)' : '#b71c1c',
+        },
+        inflows: {
+          primary: mode === 'dark' ? 'hsl(120, 40%, 55%)' : '#2e7d32',
+          surface: mode === 'dark' ? 'hsla(120, 25%, 22%, 0.6)' : '#e8f5e9',
+          text: mode === 'dark' ? 'hsl(120, 40%, 78%)' : '#1b5e20',
+        },
+      },
     },
     typography: {
       fontFamily: 'Inter, sans-serif',
@@ -285,6 +307,18 @@ export const colorSchemes = {
         hover: alpha(gray[200], 0.2),
         selected: `${alpha(gray[200], 0.3)}`,
       },
+      flows: {
+        outflows: {
+          primary: '#d32f2f',
+          surface: '#fdecea',
+          text: '#b71c1c',
+        },
+        inflows: {
+          primary: '#2e7d32',
+          surface: '#e8f5e9',
+          text: '#1b5e20',
+        },
+      },
       baseShadow:
         'hsla(220, 30%, 5%, 0.07) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.07) 0px 8px 16px -5px',
     },
@@ -293,49 +327,60 @@ export const colorSchemes = {
     palette: {
       primary: {
         contrastText: brand[50],
-        light: brand[300],
+        light: 'hsl(210, 50%, 65%)',
-        main: brand[400],
+        main: 'hsl(210, 55%, 55%)',
-        dark: brand[700],
+        dark: 'hsl(210, 50%, 35%)',
       },
       info: {
-        contrastText: brand[300],
+        contrastText: 'hsl(210, 30%, 80%)',
-        light: brand[500],
+        light: 'hsl(210, 40%, 50%)',
-        main: brand[700],
+        main: 'hsl(210, 35%, 40%)',
-        dark: brand[900],
+        dark: 'hsl(210, 30%, 25%)',
       },
       warning: {
-        light: orange[400],
+        light: 'hsl(45, 60%, 55%)',
-        main: orange[500],
+        main: 'hsl(45, 55%, 45%)',
-        dark: orange[700],
+        dark: 'hsl(45, 50%, 30%)',
       },
       error: {
-        light: red[400],
+        light: 'hsl(0, 55%, 60%)',
-        main: red[500],
+        main: 'hsl(0, 55%, 50%)',
-        dark: red[700],
+        dark: 'hsl(0, 50%, 35%)',
       },
       success: {
-        light: green[400],
+        light: 'hsl(120, 40%, 55%)',
-        main: green[500],
+        main: 'hsl(120, 40%, 45%)',
-        dark: green[700],
+        dark: 'hsl(120, 35%, 30%)',
       },
       grey: {
         ...gray,
       },
-      divider: alpha(gray[700], 0.6),
+      divider: 'hsla(0, 0%, 100%, 0.08)',
       background: {
-        default: gray[900],
+        default: darkBg,
-        paper: 'hsl(220, 30%, 7%)',
+        paper: darkPaper,
       },
       text: {
-        primary: 'hsl(0, 0%, 100%)',
+        primary: 'hsl(0, 0%, 92%)',
-        secondary: gray[400],
+        secondary: 'hsl(0, 0%, 60%)',
       },
       action: {
-        hover: alpha(gray[600], 0.2),
+        hover: 'hsla(0, 0%, 100%, 0.06)',
-        selected: alpha(gray[600], 0.3),
+        selected: 'hsla(0, 0%, 100%, 0.1)',
       },
-      baseShadow:
+      flows: {
-        'hsla(220, 30%, 5%, 0.7) 0px 4px 16px 0px, hsla(220, 25%, 10%, 0.8) 0px 8px 16px -5px',
+        outflows: {
+          primary: 'hsl(0, 55%, 60%)',
+          surface: 'hsla(0, 35%, 25%, 0.6)',
+          text: 'hsl(0, 60%, 80%)',
+        },
+        inflows: {
+          primary: 'hsl(120, 40%, 55%)',
+          surface: 'hsla(120, 25%, 22%, 0.6)',
+          text: 'hsl(120, 40%, 78%)',
+        },
+      },
+      baseShadow: '0 4px 16px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.3)',
     },
   },
 };