Platform Deep Dives

Theme System

Cascading token system for theming and branding

The client uses a cascading token system for theming.

Cascade Order

Defaults → Network → Organization → User

Each layer specifies only the overrides it needs. The merge happens in:

  • packages/client/src/core/lib/theme.ts

Tokens are applied via:

  • packages/client/src/core/providers/ThemeProvider.tsx

Theme Overrides (JSON)

Theme overrides are stored as JSON in:

  • network.theme
  • organization.theme

Supported fields include:

  • accentColor
  • bgBase, bgRaised, bgOverlay, bgPopover, bgSubtle, bgMuted
  • inkOpacity, inkSecondaryOpacity, inkTertiaryOpacity
  • lineOpacity
  • successColor, warningColor, errorColor, infoColor
  • radiusScale (sharp | default | rounded | pill)
  • font (inter | system)
  • protocolColors (per-network color map)

Example:

1{
2  "accentColor": "#0f172a",
3  "bgBase": "#f8fafc",
4  "bgRaised": "#ffffff",
5  "inkOpacity": 0.95,
6  "radiusScale": "rounded"
7}

Using Tokens in UI

Use the theme hook to access computed colors:

1import { useThemeColors } from '../core/providers/ThemeProvider';
2
3const colors = useThemeColors();
4// colors.inkTertiary, colors.accent, colors.line, etc.

Notes

  • network.primaryColor still exists as a legacy fallback for accentColor.
  • CSS variables are injected on web, while NativeWind vars() is used for native.