Themes

Customize the look and feel of the Beacon Tower interface with organization-level theming.

What is a Theme?

A theme is a resource with tag category:theme and version:v3 that controls the visual appearance of the Beacon Tower platform. Themes are applied at the organization level, allowing each organization to maintain its own branding and color scheme.

Key characteristics:

Organization scope — Each organization can have its own custom theme
Managed via Resources API — Create, update, and delete themes using the standard Resources API with theme-specific tags
Light and dark mode — Each theme defines separate color sets for both display modes
Logo integration — Themes reference uploaded logo resources for branding

Light and Dark Mode

Every theme supports both light and dark color schemes. Users can toggle between modes from the user profile menu in the top-right corner of the interface.

Each mode defines its own set of colors:

Primary — Main brand color for buttons and primary actions
Primary Dark — Hover and active states for primary elements
Link — Default text link color
Link Hover — Link color on hover
Background — Main page background color
Surface — Background color for cards, panels, and elevated surfaces
Text — Primary text color

Accessibility Note: Ensure sufficient contrast between text and background colors in both modes to meet WCAG AA standards (minimum 4.5:1 for body text).

Theme Colors

Application Colors

Application colors control the overall look of the interface:

Color	Purpose	Examples
Primary	Main brand color	Primary buttons, selected tabs, active states
Primary Dark	Emphasis variant	Button hover states, active selections
Link	Hyperlinks	Inline text links, navigation links
Link Hover	Link interaction	Link hover and focus states
Background	Page background	Main canvas color
Surface	Elevated elements	Cards, dialogs, dropdown menus
Text	Body text	Paragraphs, labels, descriptions

Navigation colors customize the left sidebar navigation:

Background — Sidebar background color
Text — Navigation item text color
Hover Background — Background color when hovering over items
Hover Text — Text color on hover
Active Background — Background for the currently active page
Active Text — Text color for the active page
Border — Sidebar border color
Sidebar Width — Width in pixels (default: 240px)
Active Border — Border accent color for active items

Status Colors

Status colors communicate system states and feedback. These colors should follow conventional meanings for accessibility:

Status	Conventional Use	Examples
Success	Positive outcomes, completed actions	Green tones (#28a745)
Info	Neutral information, guidance	Blue tones (#17a2b8)
Warning	Caution, potential issues	Yellow/orange tones (#ffc107)
Danger	Errors, destructive actions	Red tones (#dc3545)

Best Practice: Maintain conventional color associations (green for success, red for errors) to ensure users can quickly interpret system feedback.

Logos

Each theme can reference two logo resources: one for light mode and one for dark mode. This ensures logos remain visible and on-brand regardless of the user's color mode preference.

Logo Configuration

For each logo (main-light and main-dark), you can configure:

Resource ID — The ID of the uploaded logo resource
Height — Logo height in pixels
Max Width — Maximum logo width in pixels
Padding — CSS padding around the logo (e.g., "8px 16px")
Object Fit — How the logo scales within its container:
- contain — Scale to fit, maintain aspect ratio (recommended)
- cover — Fill container, may crop
- fill — Stretch to fill container
Alignment — Horizontal alignment: left, center, or right

Uploading Logos

Logos must be uploaded as resources with the category:logo tag:

curl -X POST "https://api.beacontower.ai/resources/upload" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/logo-light.svg" \
  -F "displayName=Company Logo Light" \
  -F "tags={\"category\":\"logo\"}"

Supported formats: PNG, JPG, SVG

Tip: SVG format is recommended for logos as they scale perfectly at any resolution and have smaller file sizes.

Applying Themes

Themes are applied at the organization level through the organization settings:

Navigate to Administration > Organizations
Select the organization to customize
Click Edit Organization
Select a theme from the Theme dropdown
Save changes

All users in that organization will immediately see the new theme applied across the interface.

Default Theme Behavior

If a theme is deleted or removed from an organization, the organization automatically reverts to the default Beacon Tower theme with standard branding and colors.

Theme API

Themes are stored as resources in the platform. Use the Resources API to manage themes programmatically.

Creating a Theme

curl -X POST "https://api.beacontower.ai/resources" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "displayName": "Acme Corp Theme",
  "resource_type": "user-resource",
  "tags": {
    "category": "theme",
    "version": "v3"
  },
  "document": {
    "light": {
      "colors": {
        "primary": "#d91f27",
        "primaryDark": "#b01a20",
        "link": "#0066cc",
        "linkHover": "#004499",
        "background": "#f5f5f5",
        "surface": "#ffffff",
        "text": "#333333"
      },
      "navigation": {
        "background": "#ffffff",
        "text": "#333333",
        "hoverBackground": "#f0f0f0",
        "hoverText": "#d91f27",
        "activeBackground": "#d91f27",
        "activeText": "#ffffff",
        "border": "#e0e0e0",
        "sidebarWidth": 240,
        "activeBorder": "#d91f27"
      },
      "status": {
        "success": "#28a745",
        "info": "#17a2b8",
        "warning": "#ffc107",
        "danger": "#dc3545"
      }
    },
    "dark": {
      "colors": {
        "primary": "#ff3d45",
        "primaryDark": "#d91f27",
        "link": "#66b3ff",
        "linkHover": "#3399ff",
        "background": "#1a1a1a",
        "surface": "#2d2d2d",
        "text": "#e0e0e0"
      },
      "navigation": {
        "background": "#2d2d2d",
        "text": "#e0e0e0",
        "hoverBackground": "#3d3d3d",
        "hoverText": "#ff3d45",
        "activeBackground": "#ff3d45",
        "activeText": "#ffffff",
        "border": "#404040",
        "sidebarWidth": 240,
        "activeBorder": "#ff3d45"
      },
      "status": {
        "success": "#48c774",
        "info": "#3e8ed0",
        "warning": "#ffdd57",
        "danger": "#f14668"
      }
    },
    "logos": {
      "main-light": {
        "resourceId": "logo-light-123",
        "height": 40,
        "maxWidth": 180,
        "padding": "8px 16px",
        "objectFit": "contain",
        "alignment": "left"
      },
      "main-dark": {
        "resourceId": "logo-dark-456",
        "height": 40,
        "maxWidth": 180,
        "padding": "8px 16px",
        "objectFit": "contain",
        "alignment": "left"
      }
    }
  }
}'

Updating a Theme

curl -X PATCH "https://api.beacontower.ai/resources/{resourceId}" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document": {
    "light": {
      "colors": {
        "primary": "#0066cc"
      }
    }
  }
}'

Note: PATCH requests merge with existing theme data, so you only need to include the fields you want to change.

Uploading Theme Logos

Before referencing logos in a theme, upload them as resources:

curl -X POST "https://api.beacontower.ai/resources/upload" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/logo.svg" \
  -F "displayName=Company Logo" \
  -F "tags={\"category\":\"logo\"}"

The response includes a resourceId to use in the theme document's logos section.

Resources — Learn about the resource system that stores themes
Organization Templates — Apply themes automatically to new organizations
API Reference — Full Resources API documentation

Next Steps

Design Your Theme — Choose colors that match your brand identity while maintaining accessibility
Upload Logos — Prepare light and dark versions of your logo in SVG format
Test Both Modes — Preview your theme in both light and dark modes before deploying
Apply to Organizations — Set your custom theme for each organization that needs custom branding

What is a Theme?​

Light and Dark Mode​

Theme Colors​

Application Colors​

Navigation Colors​

Status Colors​

Logos​

Logo Configuration​

Uploading Logos​

Applying Themes​

Default Theme Behavior​

Theme API​

Creating a Theme​

Updating a Theme​

Uploading Theme Logos​

Related Concepts​

Next Steps​