​

Branding & Customization

Terra provides comprehensive branding controls that allow organizations to customize the look and feel of their login page, organization identity, and footer. These settings are managed by super admins in the Settings → Organization panel.

​

Overview

Branding settings include:

• Organization Identity: Logo, name, brand color, and support email
• Footer Branding: Custom footer text and links (Privacy Policy, Terms of Service)
• Login Page Branding: Full customization of the public login page with live preview

All branding changes are automatically applied across the application and public pages.

​

Organization Identity

Configure your organization’s core branding elements that appear throughout the admin dashboard and public forms.

​

Logo

Upload your organization’s logo. Supported formats: PNG, JPG, SVG. Recommended size: 200x200px minimum. Validation: Must be a valid HTTP or HTTPS URL. Error Handling: If the logo fails to load, an error message will appear: “Failed to load image. Check the URL.” Verify the URL is accessible and the image format is supported.

​

Organization Name

The name of your organization. This appears in the header, emails, and various parts of the application.

​

Brand Color

Your organization’s primary brand color in hex format (e.g., #FF0000 or #F00). Validation: Must be a valid hex color with 3 or 6 characters after the # symbol.

​

Support Email

The email address users can contact for support. This appears in forms and status pages. Validation: Must be a valid email address or empty.

​

Footer Branding

Customize the footer that appears across the application.

​

Show Footer Branding

Toggle to show/hide the Terra branding in the footer.

​

Custom Footer Text

Add custom text to the footer (e.g., copyright notice, organization tagline).

​

Privacy Policy URL

Link to your organization’s privacy policy. Validation: Must be a valid HTTP or HTTPS URL or empty.

​

Terms of Service URL

Link to your organization’s terms of service. Validation: Must be a valid HTTP or HTTPS URL or empty.

​

Login Page Branding

The login page is the first thing users see when accessing Terra. You can fully customize its appearance with live preview of all changes.

​

Live Preview

As you edit login page settings, a live preview panel appears on the right side of the screen showing exactly how your changes will appear on the actual login page. The preview updates in real-time as you type. Desktop Layout:

• Form fields on the left
• Live preview on the right (sticky on scroll)

Mobile Layout:

• Form fields at top
• Live preview below

​

Logo

Upload a login-specific logo or leave empty to use the organization logo. This appears in the top-left corner of the login page. Fallback: If no login logo is set, the organization logo is used. If neither is set, a placeholder icon appears. Error Handling: If the image fails to load, you’ll see “Failed to load image. Check the URL.”

​

Brand Name

The text that appears next to the logo. Defaults to “Terra” if not set.

​

Background

Choose between a solid color or a background image for the left panel of the login page. Background Color:

• Default: #0f172a (slate-900)
• Validation: Must be a valid hex color

Background Image:

• Optional image URL for a more visual login page
• Validation: Must be a valid HTTP or HTTPS URL or empty
• Precedence: If both color and image are set, the image takes priority
• Overlay: A dark overlay is automatically applied over images for text readability

Mobile Behavior:

• On mobile, the background is applied to the full screen
• Text becomes white for better contrast
• The login form is wrapped in a white card with shadow for emphasis

​

Headline & Subheadline

Main text that appears on the left panel. Defaults:

• Headline: “Your benefits, simplified.”
• Subheadline: “Applying made easy.”

​

Description

Supporting text that appears below the headline. Default: “Submit your application, upload documents, and track your progress, all in one secure place. Getting help shouldn’t be complicated.”

​

Stats

Display key metrics or achievements to build trust with users. Show Stats Toggle: Enable/disable the stats section. Default Stats:

• 450k Applications processed
• ~$300M Funds disbursed
• 16+ States supported

Customization: Click “Edit Stats” to modify values and labels. You can have up to 4 stats displayed in a grid layout. Layout: Stats are displayed in a responsive grid that adjusts based on the number of stats (1-4 columns).

​

Validation

All branding fields include real-time validation to prevent invalid data:

​

URL Fields

All URL fields (logo URLs, footer links, background image) validate that:

• The value is empty (allowed), OR
• The value is a valid HTTP/HTTPS URL

Error format: "field_name: Must be a valid HTTP or HTTPS URL" Validated fields:

• logo_url
• login_logo_url
• login_background_image
• privacy_url
• terms_url

​

Color Fields

Color fields validate hex color format:

• Must start with #
• Must have exactly 3 or 6 hex characters (e.g., #F00 or #FF0000)

Error format: "field_name: Must be a valid hex color (e.g., #FF0000 or #F00)" Validated fields:

• brand_color
• login_background_color

​

Email Fields

Support email validates standard email format or allows empty value.

​

Auto-Save

Branding settings use auto-save with a 1-second debounce. Changes are automatically saved after you stop typing for 1 second. Indicators:

• “Saving…” appears while save is in progress
• Success/error messages appear after save completes
• No manual “Save” button needed

​

Image Error Handling

When an image URL fails to load (404, CORS issues, invalid format):

1. A red error banner appears below the input field
2. The error message reads: “Failed to load image. Check the URL.”
3. The error automatically clears when you change the URL
4. The previous image (or fallback) continues to display until a valid image loads

This prevents broken images from appearing on the login page and helps you identify and fix issues during configuration.

​

Audit Logging

All branding changes are logged for compliance and audit purposes (SOC 2): Tracked Fields:

• Organization identity (name, logo, color, email)
• Footer branding (text, links)
• Login page branding (logo, brand name, background color, background image, headline, subheadline, description, stats visibility, stats values)

Audit Details:

• Who made the change (user ID)
• When the change was made (timestamp)
• What changed (before/after values)

Access: View audit logs in the Settings → Audit Logs panel.

​

Permissions

View Settings: Admins and Super Admins can view branding settings Modify Settings: Only Super Admins can save branding changes This ensures brand consistency is controlled by authorized personnel only.

​

Migration

Branding settings are stored in the system_settings table. Required Migration: 008+ (includes all branding fields) Latest Migration: 080 adds login_background_image support If you see an error about missing tables, run the latest migrations in the Supabase SQL Editor.

​

Best Practices

​

Logo Images

• Use PNG with transparent background for logos
• Minimum size: 200x200px
• Keep file size under 500KB for fast loading
• Use a CDN or Supabase Storage for hosting

​

Background Images

• Recommended size: 1920x1080px or higher
• Keep file size under 2MB
• Choose images with darker areas or low contrast so white text remains readable
• Test on mobile to ensure the image works at different aspect ratios

​

Colors

• Ensure sufficient contrast between background and text
• Test in both light and dark environments
• Consider accessibility guidelines (WCAG 2.1)
• Use your brand’s official color codes

​

Text Content

• Keep headlines short and impactful (5-10 words)
• Make descriptions clear about what users should do
• Use stats that are impressive but authentic
• Update stats periodically to keep content fresh

​

Testing

• Always preview changes before users see them
• Test on mobile devices (the preview is desktop-only)
• Verify all images load correctly
• Check footer links work and go to correct URLs

​

Troubleshooting

​

”Failed to load image” error

• Verify the URL is publicly accessible (not behind authentication)
• Check for CORS restrictions on the image host
• Ensure the URL uses HTTPS (HTTP may be blocked)
• Try opening the URL in an incognito browser window

​

Colors not applying

• Verify hex format starts with #
• Check for typos in the hex code
• Ensure 3 or 6 characters after # (not 4 or 5)

​

Changes not saving

• Check your user role (must be Super Admin)
• Look for validation error messages above the form
• Verify network connection
• Check browser console for JavaScript errors

​

Preview not updating

• Try refreshing the page
• Clear browser cache if preview seems stuck
• Check that JavaScript is enabled
• Verify you’re using a supported browser (Chrome, Firefox, Safari, Edge)

​

API Reference

Branding settings are managed through server actions:

​

getSystemSettings()

Returns all system settings including branding configuration. Auth Required: Admin or Super Admin Returns: ActionResult<SystemSettings>

​

saveSystemSettings(settings)

Saves branding settings. Auth Required: Super Admin Parameters: Partial<SystemSettings> Returns: ActionResult<void> Validation: All fields are validated against the SystemSettingsInputSchema

​

getLoginPageSettings()

Public endpoint that returns login page branding for unauthenticated users. Auth Required: None (public) Returns: LoginPageSettings Usage: Called by /login page to render customized login experience.

​

Related Features

• Translations: Combine branding with multi-language support
• Custom Domains: Use your own domain with custom branding
• Status Pages: Status pages inherit organization branding settings
• Email Templates: Logos and colors are used in email notifications