Theme Customization

Overview

Kuest provides a comprehensive theming system that allows you to customize colors, corner radius, and visual appearance. All theme settings are managed through the Admin Panel under Theme.

Theme Presets

Kuest includes four built-in color presets:

Preset	Description	Use Case
Default	Standard color palette	General purpose
Midnight	Cool blue-purple tones	Discord-inspired dark theme
Lime	High-energy green accent	Bold, energetic branding
Amber	Warm amber palette	Binance-inspired warm theme

Admin Panel
Code Implementation

Navigate to Admin → Theme
Select a preset from the Preset dropdown
Click Save settings
Preview with Preview Light and Preview Dark buttons

Presets are defined in src/lib/theme.ts:

const THEME_PRESETS: Record<ThemePresetId, ThemePreset> = {
  default: {
    id: 'default',
    label: 'Default',
    description: 'Default theme palette.',
  },
  midnight: {
    id: 'midnight',
    label: 'Midnight',
    description: 'Cool blue-purple tones inspired by Discord.',
  },
  lime: {
    id: 'lime',
    label: 'Lime',
    description: 'High-energy green accent palette.',
  },
  amber: {
    id: 'amber',
    label: 'Amber',
    description: 'Warm amber palette inspired by Binance.',
  },
}

Color Tokens

Kuest uses a token-based color system with separate values for light and dark modes.

Core Surface Tokens

Token	Description
`background`	Main background color
`foreground`	Primary text color
`card`	Card background color
`card-foreground`	Card text color
`popover`	Popover background
`popover-foreground`	Popover text
`muted`	Muted background
`muted-foreground`	Muted text

Brand and Accent Tokens

Token	Description
`primary`	Primary brand color
`primary-foreground`	Text on primary
`secondary`	Secondary brand color
`secondary-foreground`	Text on secondary
`accent`	Accent highlights
`accent-foreground`	Text on accent

Outcome and Alert Tokens

Token	Description
`yes`	”Yes” outcome color
`yes-foreground`	Text on yes
`no`	”No” outcome color
`no-foreground`	Text on no
`destructive`	Error/warning color
`destructive-foreground`	Text on destructive

Input and Border Tokens

Token	Description
`border`	Border color
`input`	Input field border
`ring`	Focus ring color

Chart Tokens

Token	Description
`chart-1` through `chart-5`	Chart palette colors

Custom Color Overrides

Admin Panel
Supported Formats
JSON Override

Navigate to Admin → Theme
Scroll to Theme tokens section
Customize individual tokens for light/dark modes
Enter colors in supported formats
Click Save settings

Use the color picker or enter values manually. The reset icon restores the preset default.

Hex Colors:

#ffffff      (6-digit)
#fff         (3-digit shorthand)
#ffffff80    (8-digit with alpha)

OKLCH Colors:

oklch(0.95 0.02 180)
oklch(0.5 0.15 90 / 0.8)

OKLCH provides better perceptual uniformity and is recommended for consistent color palettes.

Advanced users can edit the JSON directly:Light overrides:

{
  "primary": "#3b82f6",
  "primary-foreground": "#ffffff",
  "background": "#ffffff",
  "foreground": "#0a0a0a"
}

Dark overrides:

{
  "primary": "#60a5fa",
  "primary-foreground": "#0a0a0a",
  "background": "#0a0a0a",
  "foreground": "#fafafa"
}

Corner Radius

Adjust the roundness of UI elements (buttons, cards, inputs).

Presets
Custom Values

Preset	Value	Description
Default	(empty)	Uses theme default
Sharp	`0`	No rounding
Soft	`0.5rem`	Subtle rounding
Round	`1rem`	Full rounding

Enter a custom CSS length value:

0 - No radius
0.25rem - Small radius
0.5rem - Medium radius
1rem - Large radius
8px - Pixel values

Only 0, px, rem, and em units are supported.

Theme Configuration Files

theme-settings.ts

Manages theme settings and database integration:

src/lib/theme-settings.ts

// Load current theme configuration
export async function loadRuntimeThemeState(): Promise<RuntimeThemeState>

// Get theme form state for admin panel
export function getThemeSettingsFormState(allSettings?: SettingsMap)

// Validate theme input
export function validateThemeSettingsInput(params: {...})

theme.ts

Core theme logic and color token handling:

src/lib/theme.ts

// Available color tokens
export const THEME_TOKENS = [
  'yes', 'yes-foreground',
  'no', 'no-foreground',
  'background', 'foreground',
  // ... 28 total tokens
]

// Build resolved theme config
export function buildResolvedThemeConfig(
  presetId: ThemePresetId,
  lightOverrides?: ThemeOverrides,
  darkOverrides?: ThemeOverrides,
  radius?: ThemeRadius | null,
)

// Generate CSS text for theme
export function buildThemeCssText(
  light: ThemeOverrides,
  dark: ThemeOverrides,
  radius?: ThemeRadius | null
)

Settings Storage

Theme settings are stored in the settings table:

Group	Key	Description
`theme`	`preset`	Theme preset ID
`theme`	`radius`	Corner radius value
`theme`	`light_json`	Light mode color overrides (JSON)
`theme`	`dark_json`	Dark mode color overrides (JSON)

Database Access

import { loadRuntimeThemeState } from '@/lib/theme-settings'

const runtimeTheme = await loadRuntimeThemeState()

console.log(runtimeTheme.theme.presetId)  // 'default'
console.log(runtimeTheme.theme.light)    // Light color overrides
console.log(runtimeTheme.theme.dark)     // Dark color overrides
console.log(runtimeTheme.theme.radius)   // Corner radius
console.log(runtimeTheme.theme.cssText)  // Generated CSS

CSS Integration

The theme system generates CSS custom properties:

:root {
  --radius: 0.5rem;
  --background: #ffffff;
  --foreground: #0a0a0a;
  --primary: #3b82f6;
  /* ... other tokens */
}

.dark,
[data-theme-mode='dark'] {
  --background: #0a0a0a;
  --foreground: #fafafa;
  --primary: #60a5fa;
  /* ... other tokens */
}

Using Theme Variables

In your components, reference theme variables:

// Tailwind classes
<div className="bg-background text-foreground">
  <button className="bg-primary text-primary-foreground rounded-[var(--radius)]">
    Button
  </button>
</div>

// Direct CSS
<div style={{ backgroundColor: 'hsl(var(--background))' }}>
  Content
</div>

Admin Theme Panel

The admin theme panel provides visual theme editing: Location: Admin → Theme Features:

Preset selector with descriptions
Corner radius slider/input
Live preview cards showing:
- Market cards
- Primary/secondary buttons
- Input fields
- Popovers
- Chart colors
Separate light/dark mode token editors
Color pickers with hex/OKLCH support
JSON editor for advanced customization
Reset buttons to restore defaults

Changes take effect immediately after saving. Users may need to refresh to see updates.

Best Practices

Color Selection

Maintain sufficient contrast ratios (WCAG AA: 4.5:1 for text)
Test colors in both light and dark modes
Use OKLCH for perceptually uniform color scales
Keep brand colors consistent across themes

Dark Mode

Don’t invert colors directly; adjust lightness
Reduce saturation slightly in dark mode
Ensure readability with proper contrast
Test with actual dark backgrounds, not pure black

Accessibility

Use semantic color tokens (primary, destructive, etc.)
Don’t rely solely on color to convey meaning
Test with color blindness simulators
Ensure focus indicators are visible

Performance

Minimize the number of custom overrides
Use presets as a base when possible
Test theme loading on slow connections
Cache theme configuration appropriately

Troubleshooting

Colors not updating

Clear browser cache and hard refresh (Ctrl+Shift+R)
Check if settings were saved successfully
Verify color format is valid (hex or OKLCH)
Ensure no CSS is overriding theme variables

Invalid color format error

Only hex (#fff, #ffffff) and OKLCH are supported
RGB/HSL must be converted to hex or OKLCH
Remove any invalid characters or spaces
Check JSON syntax if editing directly

Theme not persisting

Check database connection
Verify admin permissions
Look for errors in server logs
Ensure settings table has correct schema

Branding

Customize logos, site name, and identity

Localization

Multi-language theme labels

Admin Panel

Access the theme configuration panel

Get Started

Deployment

Configuration

Features

Customization

Operations

Overview

Theme Presets

Color Tokens

Core Surface Tokens

Brand and Accent Tokens

Outcome and Alert Tokens

Input and Border Tokens

Chart Tokens

Custom Color Overrides

Corner Radius

Theme Configuration Files

theme-settings.ts

theme.ts

Settings Storage

Database Access

CSS Integration

Using Theme Variables

Admin Theme Panel

Best Practices

Troubleshooting

Branding

Localization

Admin Panel

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

Features

Customization

Operations

​Overview

​Theme Presets

​Color Tokens

​Core Surface Tokens

​Brand and Accent Tokens

​Outcome and Alert Tokens

​Input and Border Tokens

​Chart Tokens

​Custom Color Overrides

​Corner Radius

​Theme Configuration Files

​theme-settings.ts

​theme.ts

​Settings Storage

​Database Access

​CSS Integration

​Using Theme Variables

​Admin Theme Panel

​Best Practices

​Troubleshooting

​Related Configuration

Branding

Localization

Admin Panel

Build docs developers (and LLMs) love

Overview

Theme Presets

Color Tokens

Core Surface Tokens

Brand and Accent Tokens

Outcome and Alert Tokens

Input and Border Tokens

Chart Tokens

Custom Color Overrides

Corner Radius

Theme Configuration Files

theme-settings.ts

theme.ts

Settings Storage

Database Access

CSS Integration

Using Theme Variables

Admin Theme Panel

Best Practices

Troubleshooting

Related Configuration