Your BusinessThe Contractor Codex

Branding your portal

The Contractor Codex is white-label by default. Everything your client sees — pages, PDFs, emails — is stamped with your branding. This page covers every branding lever.

Where branding settings live

/admin/settings for visual branding (business name, support email, accent color, portal greeting, logo upload). /admin/settings/email-domain for email-sending domain (separate page because it requires DNS verification).

Business name

The user-facing name that appears on every page header, PDF, and email. Set during org setup; change anytime in Settings.

The name shows up on:

  • The portal's left-side header (next to the logo)
  • Every quote, contract, and invoice PDF
  • Email "From" name + subject lines
  • The <title> tag of pages your clients see

Keep it short — 30 characters or less reads well in headers. Use your brand name, not your legal entity name.

Logo

A square PNG, ideally 512x512 or larger. Transparent background works best — the portal renders against both light and dark surfaces.

Upload from Settings. The portal stores it via the storage layer and serves it through the /api/uploads/brand-logo-{orgId}.png endpoint. Next.js's image optimizer handles resizing for different surfaces:

  • 52x52 in the portal header
  • ~150x150 on PDFs
  • 32x32 in email signatures

If you don't upload a logo, the portal falls back to /public/logo.png (the platform's default mark). That's fine for testing but you should upload your own before going live.

Accent color

A single hex color that drives every button, link, badge, focus ring, and active-state highlight in the portal. Pick from your brand identity.

Set in Settings via the color picker. The color is stored as a hex value (e.g., #e7c98b) and applied via CSS custom properties on the <body> style. No build step — change takes effect on next page load.

The accent also drives:

  • The mobile address bar color (via theme-color meta tag)
  • The PDF accent stripe on quotes and contracts
  • Email link colors

Picking a good accent

  • Saturated, not too bright — pure colors compete with text; muted saturated colors read better.
  • Sufficient contrast against white text — links + buttons use white text on the accent background. Pick a color with at least 4.5:1 contrast against #ffffff.
  • Brand-aligned — if your logo is heavy blue, picking orange creates visual conflict. Match or complement.

Some examples that work

  • #e7c98b — warm tan (platform default)
  • #3b82f6 — bright blue
  • #10b981 — emerald green
  • #f97316 — orange
  • #8b5cf6 — purple

Support email

Two-purpose field:

  • Customer-facing display. Stamped on PDF footers and "Contact us" links so your clients have an address to reach you.
  • Recipient for client-activity notifications. When set, every quote-accepted, contract-signed, change-requested, and declined notification gets routed to this address instead of your login email. Leave the field empty if you'd rather receive them at the email you signed in with.

Set in Settings. Use a real, monitored inbox. The "From" address on outbound emails comes from your email-sending domain (next section), not this field.

Email-sending domain

By default, emails from the portal go out from noreply@<platform-domain> — clients see the platform's domain, not yours. To send from your own domain (recommended for trust + deliverability):

  1. Go to Email Domain Settings.
  2. Enter your domain (e.g., acmeplumbing.com).
  3. The portal generates DNS records (SPF, DKIM, DMARC, Return-Path) — add them at your registrar.
  4. Click Verify — the portal checks the DNS and marks your domain verified.
  5. From now on, automated emails go from notifications@acmeplumbing.com (or whatever local part you choose).

DNS propagation can take up to 24 hours. The verifier checks every hour automatically.

Why bother

  • Deliverability — emails from your domain land in inboxes; emails from a generic platform domain land in spam.
  • Trust — clients are more likely to open and respond to emails from a domain they recognize.
  • Reply-to — replies go to your domain's mail, not the platform's null inbox.

Where branding shows up

SurfaceLogoNameAccent
Portal header✓✓✓ (buttons)
Quote PDF✓✓✓ (accent stripe)
Contract PDF✓✓✓
Invoice PDF (Stripe-hosted)✓✓✓
Email notifications✓ (small)✓✓ (link color)
Hosted quote page✓✓✓
Hosted signing page✓✓✓

Per-client preview

Want to see what a specific client's portal looks like with your branding? From /admin/clients, click View Portal on any client card — you'll preview their portal as them (with your branding stamped on every surface).

Multi-org branding

If a single Clerk account belongs to multiple orgs (e.g., a freelancer who works at two companies), each org has its own branding. When the user switches orgs (via the org switcher in the portal header), the branding swaps to match.

For clients who have memberships in multiple orgs' portals, same deal — they switch portals via the dashboard's org switcher.