Custom Theming Guide

This application supports a flexible theming system that allows you to override default branding, colors, and typography without modifying the core codebase.

How it Works

The application loads the default theme from src/config/theme.default.json. It then checks for a src/config/theme.custom.json file. If found, the custom configuration is merged on top of the default one.

Creating a Custom Theme

Create a file named theme.custom.json in src/config/.
Add your overrides using the structure below. You only need to include the values you want to change.

Example `theme.custom.json`

{
  "app": {
    "name": "My Custom App",
    "logo": "/logos/my-custom-logo.svg",
    "logoDark": "/logos/my-custom-logo-dark.svg",
    "favicon": "/favicon-custom.ico"
  },
  "colors": {
    "primary": "#ff5722",
    "secondary": "#2196f3",
    "background": "#f5f5f5",
    "sidebar-active-fg": "#ff5722"
  },
  "typography": {
    "fontFamily": "'Roboto', sans-serif"
  }
}

Configuration Options

App Identity (`app`)

Key	Description	Default
`name`	The name of the application, used in titles and UI.	"CoShares"
`logo`	Path to the logo image (light mode).	"/logos/CoShares_logo.svg"
`logoDark`	Path to the logo image (dark mode).	"/logos/CoShares_logo_dark.svg"
`favicon`	Path to the favicon file.	"/favicon.ico"

Colors (`colors`)

The system maps these keys to CSS variables (e.g., primary-> --primary and --color-primary).

Key	Description	Default
`primary`	Primary brand color.	`#14B8A6`
`secondary`	Secondary brand color.	`#FBBF24`
`background`	Main background color.	`#FAFAFA`
`surface`	Card/Container background color.	`#FFFFFF`
`sidebar-bg`	Sidebar background color.	`#FFFFFF`
`sidebar-fg`	Sidebar text color.	`#6B7280`
`sidebar-active-bg`	Background for active sidebar items.	`#E0F7F5`
`sidebar-active-fg`	Text color for active sidebar items.	`#0D9488`
...	(See `theme.default.json` for full list)

Typography (`typography`)

Key	Description	Default
`fontFamily`	CSS font-family stack.	`'Inter', system-ui...`

Assets

Place your custom assets (logos, favicons) in the public/ directory or a subdirectory within it (e.g., public/logos/). Reference them with an absolute path starting with /.

21 April 2026